nixos/postgresql: improve local peer authentication with default map

This allows to easily map allowed database roles to system users.

nixos/modules/services/databases/postgresql.md

@@ -170,6 +170,38 @@ are already created.
   }
 ```
 
+## Authentication {#module-services-postgres-authentication}
+
+Local connections are made through unix sockets by default and support [peer authentication](https://www.postgresql.org/docs/current/auth-peer.html).
+This allows system users to login with database roles of the same name.
+For example, the `postgres` system user is allowed to login with the database role `postgres`.
+
+System users and database roles might not always match.
+In this case, to allow access for a service, you can create a [user name map](https://www.postgresql.org/docs/current/auth-username-maps.html) between system roles and an existing database role.
+
+### User Mapping {#module-services-postgres-authentication-user-mapping}
+
+Assume that your app creates a role `admin` and you want the `root` user to be able to login with it.
+You can then use [](#opt-services.postgresql.identMap) to define the map and [](#opt-services.postgresql.authentication) to enable it:
+
+```nix
+services.postgresql = {
+  identMap = ''
+    admin root admin
+  '';
+  authentication = ''
+    local all admin peer map=admin
+  '';
+}
+```
+
+::: {.warning}
+To avoid conflicts with other modules, you should never apply a map to `all` roles.
+Because PostgreSQL will stop on the first matching line in `pg_hba.conf`, a line matching all roles would lock out other services.
+Each module should only manage user maps for the database roles that belong to this module.
+Best practice is to name the map after the database role it manages to avoid name conflicts.
+:::
+
 ## Upgrading {#module-services-postgres-upgrading}
 
 ::: {.note}