Merge remote-tracking branch 'origin/master'

docs/repository/native-postgresql/usage.adoc

@@ -88,7 +88,7 @@ Do so now to apply the configration changes.
 === Database preparation
 
 [WARNING]
-Don't use https://www.pgadmin.org/[pgAdmin] for midPoint SQL scripts!
+*Don't use https://www.pgadmin.org/[pgAdmin] for midPoint SQL scripts!*
 Explanation is in one of the important blocks below.
 
 Assuming we start in `bash` as a root or sudo capable user, let's first run `psql` as database admin:
@@ -108,6 +108,19 @@ CREATE USER midpoint WITH PASSWORD 'password' LOGIN SUPERUSER;
 CREATE DATABASE midpoint WITH OWNER = midpoint ENCODING = 'UTF8' TABLESPACE = pg_default LC_COLLATE = 'en_US.UTF-8' LC_CTYPE = 'en_US.UTF-8' CONNECTION LIMIT = -1;
 ----
 
+[NOTE]
+====
+The command above may complain about the collation on some platforms:
+
+----
+[22023] ERROR: new collation (en_US.UTF-8) is incompatible with the collation of the template database (en_US.utf8)
+Hint: Use the same collation as in the template database, or use template0 as template.
+----
+
+You can either add suggested `TEMPLATE template0` to the command, or use `en_US.utf8` locale instead
+of `en_US.UTF-8`.
+====
+
 To initialize the database connect to `midpoint` database as `midpoint` user and execute
 the content of the following schema files provided with the distribution package
 under the `doc/config/sql/native-new` directory:
@@ -230,6 +243,8 @@ EXCEPTION WHEN undefined_function THEN
 END
 $$;
 ----
++
+Check the create script for all occurrenes of `CREATE EXTENSION` and run them manually.
 
 . Run the rest of the SQL script as user `midpoint`:
 +
@@ -244,6 +259,11 @@ You can ignore such errors, as the extensions were created by superuser in previ
 . Continue installation process normally, which means executing the audit SQL script `postgres-new-audit.sql`
 and script for Quartz tables `postgres-new-quartz.sql`.
 
+[WARNING]
+With this setup you have to be careful with upgrade scripts as well.
+*Always check the upgrade SQL script for new `CREATE EXTENSION` and run those as superuser first!*
+Afterwards, you can run the whole upgrade script as the normal user (`midpoint` in this example).
+
 == midPoint Configuration
 
 At this moment the database is prepared and it's time to configure midPoint appropriately.

docs/upgrade/database-schema-upgrade.adoc

@@ -83,6 +83,14 @@ If both repository and audit is in the same database, use both scripts on the sa
 
 The scripts do not contain any version number and are safe to run repeatedly - only the missing changes are applied.
 
+[IMPORTANT]
+====
+If you created the schema objects as non-superuser as described xref:/midpoint/reference/repository/native-postgresql/usage/#installing-as-non-superuser[here],
+be sure to run all the missing `CREATE EXTENSION` commands as a superuser first!
+This is also a good reason to use `-v ON_ERROR_STOP=1` flag with the `psql` - as shown below.
+This stops the upgrade when the first such problem occurs, but works fine if the extension already exists.
+====
+
 To upgrade the main repository run this command:
 [source,bash]
 ----

docs/upgrade/upgrade-guide.adoc

@@ -176,14 +176,23 @@ Database upgrade is thoroughly described in xref:/midpoint/reference/upgrade/dat
 There are also deployment specific details to consider, e.g. is the audit in the same database?
 
 For example, using the recommended xref:/midpoint/reference/repository/native-postgresql/[Native repository]
-based on PostgreSQL, one can upgrade the database using the `psql` tool (considering the audit and the main repository are in a single database):
+based on PostgreSQL, one can upgrade the database using the `psql` tool
+(considering the audit and the main repository are in a single database):
 
 [source,bash]
 ----
 psql -v ON_ERROR_STOP=1 -h localhost -U midpoint -W -d midpoint \
   -f postgres-new-upgrade.sql -f postgres-new-upgrade-audit.sql
 ----
 
+[IMPORTANT]
+====
+If you created the schema objects as non-superuser as described xref:/midpoint/reference/repository/native-postgresql/usage/#installing-as-non-superuser[here],
+be sure to run all the missing `CREATE EXTENSION` commands as a superuser first!
+This is also a good reason to use `-v ON_ERROR_STOP=1` flag with the `psql` - as shown above.
+This stops the upgrade when the first such problem occurs, but works fine if the extension already exists.
+====
+
 The upgrade script is non-destructive.
 It changes database schema, but it does not affect the data.
 Database schema changes between midPoint versions are usually backwards-compatible.