diff --git a/nixos/doc/manual/redirects.json b/nixos/doc/manual/redirects.json
index 4385b88e7cea..25ed9820478f 100644
--- a/nixos/doc/manual/redirects.json
+++ b/nixos/doc/manual/redirects.json
@@ -1438,6 +1438,9 @@
   "module-services-postgres-upstream-deviation": [
     "index.html#module-services-postgres-upstream-deviation"
   ],
+  "module-services-postgresql-target-vs-service": [
+    "index.html#module-services-postgresql-target-vs-service"
+  ],
   "module-services-foundationdb": [
     "index.html#module-services-foundationdb"
   ],
diff --git a/nixos/modules/services/databases/postgresql.md b/nixos/modules/services/databases/postgresql.md
index 7e114b0a6ce9..bea8df36a219 100644
--- a/nixos/modules/services/databases/postgresql.md
+++ b/nixos/modules/services/databases/postgresql.md
@@ -485,6 +485,35 @@ with hardening, it's considered a bug.
 When using extensions that are not packaged in `nixpkgs`, hardening adjustments may
 become necessary.
 
+## `postgresql.service` vs `postgresql.target` {#module-services-postgresql-target-vs-service}
+
+In order to delay a service's startup until the local PostgreSQL instance is up, one usually uses a combination of `wants`/`after`, i.e.
+
+```nix
+{
+  systemd.services.myservice = {
+    wants = [ "postgresql.target" ];
+    after = [ "postgresql.target" ];
+  };
+}
+```
+
+::: {.note}
+`wants` makes sure that `postgresql.target` is being started when `myservice.service` is started.
+If it's necessary to restart `myservice` when `postgresql.target` gets restarted and `myservice.service` fails to start if `postgresql.service` fails to start, use `requires` instead.
+
+See also {manpage}`systemd.unit(5)`.
+:::
+
+It's also possible to wait for `postgresql.service` instead, however that has a slightly different meaning:
+
+* `postgresql.service` is `active` if the database is __at least__ in read-only mode.
+* `postgresql.target` is `active` if the database is either in __read-write__ mode or a standby server.
+
+This is implemented by making `postgresql.target` wait for `postgresql-setup.service` which waits for the database to be fully up and applies the changes necessary for `ensureUsers`.
+
+Restarting `postgresql.service` by hand also triggers a restart of `postgresql.target`.
+
 ## Notable differences to upstream {#module-services-postgres-upstream-deviation}
 
 - To avoid circular dependencies between default and -dev outputs, the output of the `pg_config` system view has been removed.