From 0aa1459e31c386514690eaa92b86b11f71412faa Mon Sep 17 00:00:00 2001
From: Kamil Páral <kparal@redhat.com>
Date: Nov 30 2023 14:55:12 +0000
Subject: docs: use postgresql tools from the container


The host system tools are often at a different version, which can present issues
when dumping or restoring the database (e.g. unknown option errors). Change
the docs to always use postgresql tools from the container.

---

diff --git a/docs/source/development.rst b/docs/source/development.rst
index 7c8afbe..0345baf 100644
--- a/docs/source/development.rst
+++ b/docs/source/development.rst
@@ -16,8 +16,7 @@ The instructions below will use virtualenv so that there are no potential confli
   python3-devel \
   libcurl-devel \
   krb5-devel \
-  openssl-devel \
-  postgresql
+  openssl-devel
 
 
 .. _set-up-database:
@@ -41,7 +40,7 @@ Run a `Podman`_ container with the latest `PostgreSQL image`_::
 
 Wait 10 seconds to let the dabatase initialize and then check that it works::
 
-  $ psql --host=localhost --username=postgres --command='select version();'
+  $ podman exec -it blockerbugsdb psql --host=localhost --username=postgres --command='select version();'
   Password for user postgres:
 
                 version
@@ -49,8 +48,6 @@ Wait 10 seconds to let the dabatase initialize and then check that it works::
   PostgreSQL 13.3 (Debian 13.3-1.pgdg100+1) on x86_64-pc-linux-gnu ...
   (1 row)
 
-If you don't want to type in your password every time, `set up`__ ``~/.pgpass``.
-
 Hint: With Podman, you can start, stop, and list existing containers like this::
 
   podman start blockerbugsdb
@@ -62,7 +59,6 @@ Hint: With Podman, you can start, stop, and list existing containers like this::
 
 .. _Podman: https://podman.io/whatis.html
 .. _PostgreSQL image: https://hub.docker.com/_/postgres
-__ https://www.postgresql.org/docs/current/libpq-pgpass.html
 
 
 Create a Virtualenv
diff --git a/docs/source/development_tasks.rst b/docs/source/development_tasks.rst
index 27f12c7..81a9d7a 100644
--- a/docs/source/development_tasks.rst
+++ b/docs/source/development_tasks.rst
@@ -41,11 +41,23 @@ You can use ``pg_dump`` or ``pg_dumpall`` to back up the whole database, and ``p
 
 __ https://snapshooter.com/learn/postgresql/pg_dump_pg_restore
 
-Here's an example of a backup and restore::
+.. note::
+    The version of tools needs to match the version of the database, otherwise you might encounter errors. Therefore the safest route is to run the tools directly from the database container.
 
-  pg_dump --host=localhost --username=postgres --format=custom --file=blockerbugs.pgdump blockerbugs
+Here's an example of a backup::
+
+  podman start blockerbugsdb
+  podman exec -it blockerbugsdb pg_dump --host=localhost --username=postgres --format=custom --file=/blockerbugs.pgdump blockerbugs
+  # copy the backup file to the current directory
+  podman cp blockerbugsdb:/blockerbugs.pgdump .
+
+And an example of restoring it::
+
+  # copy the backup file into the container
+  podman cp ./blockerbugs.pgdump blockerbugsdb:/
+  podman start blockerbugsdb
   # the following will completely drop and recreate the blockerbugs db
-  pg_restore --host=localhost --username=postgres --dbname=postgres --clean --create blockerbugs.pgdump
+  podman exec -it blockerbugsdb pg_restore --host=localhost --username=postgres --dbname=postgres --clean --create /blockerbugs.pgdump
 
 
 podman commit
@@ -84,14 +96,19 @@ If you want to display and optionally edit/backup/restore the tables in a GUI cl
 .. _Sequeler: https://flathub.org/apps/details/com.github.alecaddd.sequeler
 __ https://wiki.postgresql.org/wiki/PostgreSQL_Clients#Open_Source
 
+Hint: If you don't want to type in your password every time with *pgAdmin* or other clients, `set up`__ ``~/.pgpass``.
+
+__ https://www.postgresql.org/docs/current/libpq-pgpass.html
+
 
 Resetting the database
 ----------------------
 
 If you want to simply reset the *blockerbugs* database into the default empty state (i.e. no tables), instead of restoring from a backup, you can either a) remove the current container and create :ref:`a new one from scratch <set-up-database>`, or b) you can even faster drop the existing database and create a new empty one like this::
 
-  dropdb --host=localhost --username=postgres blockerbugs
-  createdb --host=localhost --username=postgres blockerbugs
+  podman start blockerbugsdb
+  podman exec -it blockerbugsdb dropdb --host=localhost --username=postgres blockerbugs
+  podman exec -it blockerbugsdb createdb --host=localhost --username=postgres blockerbugs
 
 You can then continue with :ref:`initializing the environment <initializing_env>`.