From e3fabc93602bd3b0ed4748c6cf983244b5830d50 Mon Sep 17 00:00:00 2001
From: Maximilian Bosch <maximilian@mbosch.me>
Date: Sat, 14 Jun 2025 23:25:43 +0200
Subject: [PATCH] nixos/postgresql: fix docs on default package

Closes #416595

(cherry picked from commit e6cc23ba3f5ba406da5b4e1b045a23f0e8df41d3)
---
 .../modules/services/databases/postgresql.md  |  7 ++++++-
 .../modules/services/databases/postgresql.nix | 19 +++++++++++++++++--
 2 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/nixos/modules/services/databases/postgresql.md b/nixos/modules/services/databases/postgresql.md
index e1256c9672f2..c07db1e00576 100644
--- a/nixos/modules/services/databases/postgresql.md
+++ b/nixos/modules/services/databases/postgresql.md
@@ -21,7 +21,12 @@ To enable PostgreSQL, add the following to your {file}`configuration.nix`:
   services.postgresql.package = pkgs.postgresql_15;
 }
 ```
-Note that you are required to specify the desired version of PostgreSQL (e.g. `pkgs.postgresql_15`). Since upgrading your PostgreSQL version requires a database dump and reload (see below), NixOS cannot provide a default value for [](#opt-services.postgresql.package) such as the most recent release of PostgreSQL.
+
+The default PostgreSQL version is approximately the latest major version available on the NixOS release
+matching your [`system.stateVersion`](#opt-system.stateVersion).
+This is because PostgreSQL upgrades require a manual migration process (see below).
+Hence, upgrades must happen by setting [`services.postgresql.package`](#opt-services.postgresql.package)
+explicitly.
 
 <!--
 After running {command}`nixos-rebuild`, you can verify
diff --git a/nixos/modules/services/databases/postgresql.nix b/nixos/modules/services/databases/postgresql.nix
index 48ff4c2a48ef..dc8b05b46458 100644
--- a/nixos/modules/services/databases/postgresql.nix
+++ b/nixos/modules/services/databases/postgresql.nix
@@ -120,8 +120,22 @@ in
 
       enableJIT = mkEnableOption "JIT support";
 
-      package = mkPackageOption pkgs "postgresql" {
-        example = "postgresql_15";
+      package = mkOption {
+        type = types.package;
+        example = literalExpression "pkgs.postgresql_15";
+        defaultText = literalExpression ''
+          if versionAtLeast config.system.stateVersion "24.11" then
+            pkgs.postgresql_16
+          else if versionAtLeast config.system.stateVersion "23.11" then
+            pkgs.postgresql_15
+          else if versionAtLeast config.system.stateVersion "22.05" then
+            pkgs.postgresql_14
+          else
+            pkgs.postgresql_13
+        '';
+        description = ''
+          The package being used by postgresql.
+        '';
       };
 
       finalPackage = mkOption {
@@ -656,6 +670,7 @@ in
             See also https://endoflife.date/postgresql
           '';
         base =
+          # XXX Don't forget to keep `defaultText` of `services.postgresql.package` up to date!
           if versionAtLeast config.system.stateVersion "24.11" then
             pkgs.postgresql_16
           else if versionAtLeast config.system.stateVersion "23.11" then