adapt docs

Author: 3nids

docs/docs/cli.md

@@ -1,4 +1,4 @@
-usage: pum [-h] [-c CONFIG_FILE] -p PG_CONNECTION [-d DIR] [-v] [-q] [--version] {info,install,upgrade,role,check,dump,restore,baseline,uninstall} ...
+usage: pum [-h] [-c CONFIG_FILE] -p PG_CONNECTION [-d DIR] [-v] [-q] [--version] {info,install,upgrade,role,check,dump,restore,baseline,uninstall,app} ...
 ### options:
 - `-h, --help`: show this help message and exit
 - `-c CONFIG_FILE, --config_file CONFIG_FILE`: set the config file. Default: .pum.yaml
@@ -9,7 +9,7 @@ usage: pum [-h] [-c CONFIG_FILE] -p PG_CONNECTION [-d DIR] [-v] [-q] [--version]
 - `--version`: Show program's version number and exit.
 ### commands:
 valid pum commands
-{info,install,upgrade,role,check,dump,restore,baseline,uninstall}
+{info,install,upgrade,role,check,dump,restore,baseline,uninstall,app}
 - `info`: show info about schema migrations history.
 - `install`: Installs the module.
 - `upgrade`: Upgrade the database.
@@ -19,3 +19,4 @@ valid pum commands
 - `restore`: restore a Postgres database from a dump file
 - `baseline`: Create upgrade information table and set baseline
 - `uninstall`: Uninstall the module by executing uninstall hooks
+- `app`: Manage application handlers (create, drop, recreate)

docs/docs/cli/app.md

@@ -0,0 +1,6 @@
+usage: pum app [-h] [-p PARAMETER PARAMETER] {create,drop,recreate}
+### positional arguments:
+- `{create,drop,recreate}`: Action to perform: create (run create_app handlers), drop (run drop_app handlers), recreate (run drop then create)
+### options:
+- `-h, --help`: show this help message and exit
+- `-p PARAMETER PARAMETER, --parameter PARAMETER PARAMETER`: Assign variable for running SQL handlers. Format is name value.

docs/docs/parameters.md

@@ -12,6 +12,7 @@ Each parameter accepts:
 - **type** *(optional, default: `text`)*: One of `boolean`, `integer`, `text`, `decimal`, `path`.
 - **default** *(optional)*: A default value used for validation.
 - **description** *(optional)*: A human-readable description.
+- **app_only** *(optional, default: `false`)*: If `true`, the parameter can be changed freely when recreating the app. Standard parameters (`app_only: false`) must keep the same value across the entire module lifecycle (install, upgrade, create-app).
 
 ```yaml
 parameters:
@@ -27,8 +28,27 @@ parameters:
   - name: my_flag
     type: boolean
     default: true
+
+  - name: view_comment
+    type: text
+    default: my comment
+    description: Comment used when creating application views.
+    app_only: true
 ```
 
+### Standard vs. app-only parameters
+
+PUM stores the parameter values used during each migration in the `pum_migrations` table.
+On every subsequent **upgrade**, **create app**, or **recreate app** call, PUM compares the
+provided parameter values against the stored ones:
+
+- **Standard parameters** (`app_only: false`, the default) must remain unchanged. If a
+  different value is provided, PUM raises an error. This protects structural values
+  (e.g. an SRID) that would cause data inconsistencies if changed after installation.
+- **App-only parameters** (`app_only: true`) are allowed to change between calls. Use
+  this for values that only affect application-level objects such as views or comments,
+  which are dropped and recreated anyway.
+
 ## Passing values from the CLI
 
 Parameter values are provided at runtime via the `-p` / `--parameter` flag, which takes a name and a value:

pum/config_model.py

@@ -21,15 +21,15 @@ class ParameterDefinitionModel(PumCustomBaseModel):
         description: Optional description of the parameter.
         app_only: If True, the parameter can be changed when recreating the app.
             Standard parameters (app_only=False) must remain the same across
-            the whole application lifecycle.
+            the whole module lifecycle.
     """
 
     name: str
     type: ParameterType = Field(default=ParameterType.TEXT, description="Type of the parameter")
     default: Any | None = None
     description: str | None = None
     app_only: bool = Field(
-        default=False, description="If True, the parameter can be changed when recreating the app."
+        default=False, description="If True, the parameter can be adapted when recreating the app."
     )
 
     @model_validator(mode="before")