From 23d916a8ab0bc08ff6e998c9b9b52e112ad9dabc Mon Sep 17 00:00:00 2001
From: Rikard Bartholf <rikard@bartholf.nu>
Date: Tue, 10 Sep 2024 15:07:51 +0200
Subject: [PATCH] Update README for pwdb

---
 bin/pwdb.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 61 insertions(+), 6 deletions(-)

diff --git a/bin/pwdb.md b/bin/pwdb.md
index 67eea2c..4e22317 100644
--- a/bin/pwdb.md
+++ b/bin/pwdb.md
@@ -1,8 +1,63 @@
+# Infra-Tools-n-Stuff
 
-Add a dumped file to local machine
-You often have the address in your .pgpass
-`./pwdb dump [address]`
+### pwdb
 
-Sync the downloaded file to your localhost with 4 cores
-`./pwdb sync [address] localhost -j 4 -p`
-To get a production db with grants
+A script that simplifies:
+
+- Dumping the production database
+- Restore a dump to local development server or stage
+
+##### Prerequisites
+
+- `~/.pgpass` with password set for the user root is required for this script to run.
+  User root must have super privileges.
+- Prior using this script, the super-user root must be present.
+- For stage: Set the timezone of the database to Europe/Paris in RDS-config. _(Europe/Stockholm is not yet supported by Aurora)_
+- Before deploying to stage, the following users must be present.
+  - funnel
+  - datastudio
+
+##### Configure user root as super user
+
+```sql
+CREATE ROLE root WITH PASSWORD 'secret' LOGIN;
+
+-- For Amazon RDS
+GRANT rds_superuser TO root;
+
+-- For other instances
+ALTER USER root WITH SUPERUSER;
+```
+
+##### Usage
+
+```
+    Usage: pwdb [OPTION]... [COMMAND] [SOURCE] <TARGET>
+
+    Commands:
+        dump <source>           dump database photowall from SOURCE
+        sync <source> <target>  sync database photowall from SOURCE database to TARGET database
+
+    Options:
+        -d, --dry-run           don't actually run any commands, just print them
+        -h, --help              display this help message
+        -j, --jobs <num>        (DEFAULT: 1) number of processes to use when restoring the dump
+        -p, --production        tells if the restored database is production like (stage or prod).
+                                If set, additional grants will be handled
+```
+
+##### Examples
+
+```bash
+# Create a fresh backup of production database and restore to local development environment
+$ pwdb sync url.to.production.server localhost
+
+# Create a fresh backup of production database and restore to the staging environment
+$ pwdb sync url.to.production.server url.to.local.server
+
+# Create a fresh backup of production server.
+$ pwdb dump url.to.production.server
+```
+
+Location of the downloaded database dump is `~/photowall.sql`.
+If the file already exists when trying to sync, you are asked if you want to use the existing file or create a new.