postgres: Add setupSchemaScript option for Schema Setup

Path to a script that will set up or update the PostgreSQL database schema.

This script must be idempotent, meaning it can be run multiple times without causing unintended side effects. If you change your schema dynamically, ensure that this script handles such cases gracefully to maintain database integrity.

examples/postgres/devenv.nix

@@ -11,5 +11,8 @@
     initialScript = ''
       CREATE EXTENSION IF NOT EXISTS postgis;
     '';
+    setupSchemaScript = ''
+      echo "script to run to setup or update database schema. This script must be idempotent."
+    '';
   };
 }

src/modules/services/postgres.nix

@@ -98,6 +98,15 @@ let
     ''
     else "";
 
+  runSetupSchemaScript =
+    if cfg.setupSchemaScript == null
+    then ''
+      echo "script not provided, skipping."
+    ''
+    else ''
+      ${cfg.setupSchemaScript}
+    '';
+
   toStr = value:
     if true == value
     then "yes"
@@ -158,10 +167,29 @@ let
     fi
     unset POSTGRES_RUN_INITIAL_SCRIPT
   '';
+
+  setupSchemaScript = pkgs.writeShellScriptBin "setup-schema-script" ''
+    echo
+    echo "PostgreSQL is setting up the schema"
+    echo
+    OLDPGHOST="$PGHOST"
+    PGHOST=${q runtimeDir}
+
+    pg_ctl -D "$PGDATA" -w start -o "-c unix_socket_directories=${runtimeDir} -c listen_addresses= -p ${toString cfg.port}"
+    ${runSetupSchemaScript}
+    pg_ctl -D "$PGDATA" -m fast -w stop
+    PGHOST="$OLDPGHOST"
+    unset OLDPGHOST
+    echo
+    echo "PostgreSQL setup schema complete."
+    echo
+  '';
+
   startScript = pkgs.writeShellScriptBin "start-postgres" ''
     set -euo pipefail
     mkdir -p ${q runtimeDir}
     ${setupScript}/bin/setup-postgres
+    ${setupSchemaScript}/bin/setup-schema-script
     exec ${postgresPkg}/bin/postgres
   '';
 in
@@ -327,6 +355,18 @@ in
       '';
     };
 
+    setupSchemaScript = lib.mkOption {
+      type = types.nullOr types.str;
+      default = null;
+      description = ''
+        Path to a script that will set up or update the PostgreSQL database schema. This script must be idempotent, meaning it can be run multiple times without causing unintended side effects. 
+        If your schema changes dynamically, ensure that this script handles such cases gracefully to maintain database integrity.
+      '';
+      example = lib.literalExpression ''
+        "path/to/your/schema/setup/script.sh"
+      '';
+    };
+
     hbaConf = lib.mkOption {
       type = types.nullOr types.str;
       default = null;

tests/postgresql-localhost/devenv.nix

@@ -6,5 +6,8 @@
     initialScript = ''
       CREATE USER postgres SUPERUSER;
     '';
+    setupSchemaScript = ''
+      echo "script to run to setup or update database schema. This script must be idempotent."
+    '';
   };
 }