From 9d5293dbab7171ee876c3e70ae6b477130e1f29b Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc kop@karlpinc.com" Date: Mon, 9 Oct 2023 01:37:30 +0000 Subject: [PATCH] Improve cluster creation docs --- make_files/make_cluster.mk | 52 ++++++++++++++++++++++++++------------ 1 file changed, 36 insertions(+), 16 deletions(-) diff --git a/make_files/make_cluster.mk b/make_files/make_cluster.mk index 882ba30..1a54961 100644 --- a/make_files/make_cluster.mk +++ b/make_files/make_cluster.mk @@ -77,20 +77,36 @@ ## ## 1) If you already have a Postgres role that can login, create ## roles, and create databases then that role should be used as -## the administrative user. Otherwise, first create an -## administrative user (while logged in to Unix as root) with -## "create-adminuser". +## the administrative user. If this role is your personal role, +## after step 2, execute "GRANT admin TO YourRole;" and skip step +## 3. Otherwise, first create an administrative user (while +## logged in to Unix as root) with "create-adminuser". ## ## 2) Use the administrative user to create the "group" roles -## ("create-groups") and then the database ("init-database"). -## Hint: Use TARGET_DB=postgres for all of this, since your new -## database won't yet exist. +## ("create-groups"). ## -## 3) Drop the "public" schema. If you are using PG v15 or later use -## the "drop-public" target. If you have an administrative user -## it can be used with the "drop-public" target. Otherwise use -## the "drop-public-root" target while logged in to Unix as the -## root user. +## Hint: Use TARGET_DB=postgres for this, since your new database +## won't yet exist. +## +## 3) Use the SokweDB tools to create a (personal) SokweDB +## administrative user. Use this user from this point forward +## when performing administrative tasks. A personal development +## login can be created as well but regular logins cannot be +## created until after database creation, step 4. +## +## Hint: Use the command line targets to install command line +## SokweDB user management tools. +## +## Tip: If using psql, use the "\password" command to set passwords. +## +## 4) Create the databases ("init-database"). SokweDB is expecting +## databases named "sokwedb", "sokwedb_test", and "sokwedb_dev". +## +## 5) Drop the "public" schema from all databases. If you are using +## PG v15 or later use the "drop-public" target. If you have an +## administrative user it can be used with the "drop-public" +## target. Otherwise use the "drop-public-root" target while +## logged in to Unix as the root user. ## ## The "init-database" target creates a database owned by the admin group. ## @@ -218,11 +234,15 @@ create-groups: db/creategroups.sql | psql $(PSQL_ARGS) $(PSQL_SINGLE_TRANS) --set=ON_ERROR_STOP=y ## init-database Create and initialize the database named by the -## TARGET_DB variable. This target may be used by a -## regular, non-root, Unix user. To create the db the -## ADMINUSER variable is used. Note: Does not run in a -## transaction. Can create the database and then fail, -## leaving the cluster in an unusual state. +## TARGET_DB variable. This target may be used +## by a regular, non-root, Unix user. To create +## the db the ADMINUSER variable is used. +## Caution: The ADMINUSER must be a sokwedb admin +## user, created with sokwedb tools. Note: Does +## not run in a transaction. Can create the +## database and then fail, leaving the cluster in +## an unusual state. + .PHONY: init-database init-database: $(GENERATED_SHELL) $(PSQL_DEPENDS) [ -n "$(TARGET_DB)" ] \ -- 2.34.1