From b34fb24ed24296ac90a258d3b618c928334f611f Mon Sep 17 00:00:00 2001
From: MitchLloyd <mitch@codeyourfuture.io>
Date: Thu, 18 Apr 2024 15:37:49 +0100
Subject: [PATCH] port workshop formatting to setup guide (#491)

* take sally's instructions and put them into the db setup guide

* rm comments

* tidy up readme

---------

Co-authored-by: Dedekind561 <mitchell.lloyd154@gmail.com>
---
 guides/db-setup/readme.md | 84 ++++++++++++++++++++++++++++++++++-----
 1 file changed, 73 insertions(+), 11 deletions(-)

diff --git a/guides/db-setup/readme.md b/guides/db-setup/readme.md
index 0fd1df4a6d..7ad569cb0e 100644
--- a/guides/db-setup/readme.md
+++ b/guides/db-setup/readme.md
@@ -1,36 +1,98 @@
 # Local database setup ⚙️
 
-## Initiating local database
+## Initialising the Database
 
-Once you have your schema ready, make sure you create a new database for yourself locally. For example, let's call it `videorec`. From a shell use `createdb` to create a new database for yourself:
+### Create a local database
+
+Use the `createdb` command to create a new database called `videorec`:
 
 ```bash
 createdb videorec
 ```
 
-Once it is created you can now try to load your file into the database using `psql`:
+### Create tables and load data
+
+Create tables and load the database with initial data:
 
 ```bash
 psql -d videorec < db/initdb.sql
 ```
 
-**Note:** Depending on how postgresql was installed for you, you might need to add some connectivity details to both `createdb` and `psql`:
+#### Summary
+
+1. `psql` : Use the PostgreSQL command-line interface.
+2. `-d` : This flag marks the next argument as the database name.
+3. `videorec` : The name of the database you want to populate.
+4. `<` : The following file will be used as input.
+5. `db/initdb.sql` : The path to the SQL file to populate the database.
+
+Depending how postgresql was installed for you, you might need to add some connectivity details to both createdb and psql: `psql -h localhost -U username -d videorec < db/initdb.sql` In this example you ask postgres to connect to your local database through localhost and use username as the user.
+
+##### Check 📝
+
+Double-check the command you just used was successful. What should you expect to see in your local database after running this command.
+
+### Backup your database
+
+Now, let's create a compressed archive of your database for safekeeping. Use the `pg_dump` command with the following options:
+
+```bash
+pg_dump -h localhost -U username videorec > videorec_backup.sql.gz
+```
+
+##### Explanation
+
+- `pg_dump`: This command is designed specifically for creating PostgreSQL database backups.
+- `-h localhost` (Optional): Specify the host (`localhost` in most cases) if your PostgreSQL installation differs.
+- `-U username` (Optional): Include your username if required for connection.
+- `videorec`: This is the name of the database you want to back up.
+- `> videorec_backup.sql.gz`:\*\* This defines the filename and format for the backup. The `>` redirects the output to a file, and `.sql.gz` indicates a gzipped SQL archive.
+
+**Verification:** Check your terminal or file explorer to confirm the existence of the backup file (`videorec_backup.sql.gz`).
+
+#### Stretch: Customize Backup Location
+
+- You can modify the output filename and location to suit your preference. For example:
+
+```bash
+pg_dump -h localhost -U username videorec > backups/videorec_backup_$(date +"%Y-%m-%d").sql.gz
+```
+
+- This command incorporates the current date in the filename for easy identification and versioning.
+
+### Removing, Re-initializing, and Restoring
+
+Now that we have a backup, let's practice removing and re-initializing the database:
+
+#### 1. Drop the Database
+
+Use the `dropdb` command followed by the database name (`videorec`) to remove the database:
 
 ```bash
-psql -h localhost -U username -d videorec < db/initdb.sql
+dropdb videorec
 ```
 
-In this example, we ask postgres to connect to your local database through `localhost` and use `username` as the user.
+**Confirmation:** Verify that the database is gone by trying to connect to it with `psql -d videorec`. You should receive an error message indicating the database doesn't exist.
 
-## Re-running the script
+#### 2. Recreate the Database
 
-It is advised to make sure that the `initdb.sql` script can be run multiple times, and each run would reset the database to a known initial state. One way to do it is to add some SQL code to the start that would delete tables in case they exist, something like:
+Use the same `createdb` command from before to create a new empty database with the same name (`videorec`):
 
-```sql
-DROP TABLE IF EXISTS videos CASCADE;
+```bash
+createdb videorec
+```
+
+#### 3. Restore from Backup
+
+Use `psql` with the `-f` flag to specify the backup file and restore the data into the newly created database:
+
+```bash
+psql -d videorec -f videorec_backup.sql.gz
 ```
 
-Try running your `initdb.sql` script multiple times with the `psql` code above to make sure every time you get a fresh and clean database without errors.
+#### 4. Verify
+
+Connect to the database (`psql -d videorec`) to confirm the tables and data have been restored successfully.
 
 ## Sample data