rename hook to create/drop app (#150)

* rename hooks to create/drop app

* use ApplicationHooksModel

* Add backward compatibility for legacy migration_hooks/pre/post config format

- Enable Pydantic to accept both old and new field names via aliases
- ApplicationHookModel accepts 'pre'/'post' as aliases for 'drop'/'create'
- ConfigModel accepts 'migration_hooks' as alias for 'application_hooks'
- Add model validators to handle legacy field name conversion
- All existing tests pass + new backward compatibility test added
- Both old format (.pum.yaml with migration_hooks/pre/post) and new format work seamlessly

* yaml to files

* reorganize

Author: 3nids

BACKWARD_COMPATIBILITY.md

@@ -0,0 +1,15 @@
+# Backward Compatibility for Hook Configuration
+
+## Overview
+
+PUM now supports reading legacy `.pum.yaml` files that use the old field names `migration_hooks`, `pre`, and `post`. This ensures smooth migration for users upgrading to the new terminology.
+
+## What Changed
+
+The refactoring renamed hook-related fields for better clarity:
+- **Old**: `migration_hooks` with `pre`/`post` hooks
+- **New**: `application_hooks` with `drop`/`create` hooks
+
+## Future Considerations
+
+While backward compatibility is fully supported, we recommend updating `.pum.yaml` files to the new format at your convenience for clarity and consistency with documentation.

README.md

@@ -16,7 +16,7 @@ PUM (PostgreSQL Upgrades Manager) is a robust database migration management tool
 - **Command-line and Python Integration**: Use PUM as a standalone CLI tool or integrate it into your Python project.
 - **Database Versioning**: Automatically manage database versioning with a metadata table.
 - **Changelog Management**: Apply and track SQL delta files for database upgrades.
-- **Migration Hooks**: Define custom hooks to execute additional SQL or Python code before or after migrations. This feature allows you to isolate data (table) code from application code (such as views and triggers), ensuring a clear separation of concerns and more maintainable database structures.
+- **Migration Hooks**: Define custom hooks to execute additional SQL or Python code to drop or create the application schema during migrations. This feature allows you to isolate data (table) code from application code (such as views and triggers), ensuring a clear separation of concerns and more maintainable database structures.
 
 ## Why PUM?
 

docs/docs/configuration/configuration.md

@@ -6,7 +6,7 @@ In the config file `.pum.yaml`, you can define, with the YAML syntax:
 
 * `changelogs_directory`: the directory with the changelogs files.
 * `parameters`: the definition of parameters for the migration.
-* `migrations_hooks`: the `pre` and `post` migrations hooks.
+* `application_hooks`: the `drop` and `create` application schema hooks.
 
 For example:  
 ```yaml

docs/docs/configuration/migration_hooks_model.md

@@ -1,3 +1,3 @@
-# MigrationHooksModel
+# ApplicationHookModel
 
-::: pum.config_model.MigrationHooksModel
+::: pum.config_model.ApplicationHookModel

docs/docs/hooks.md

@@ -1,23 +1,23 @@
 # Migration hooks
 
-Migration hooks allow you to define actions to be executed before or after a migration. These hooks are defined in the `.pum.yaml` configuration file under the `migration_hooks` section.
+Migration hooks allow you to define actions to be executed during the migration process. These hooks are defined in the `.pum.yaml` configuration file under the `application_hooks` section.
 
 There are two types of migration hooks:
 
-- `pre`: Executed before the migration.
-- `post`: Executed after the migration.
+- `drop`: Hooks to drop the application schema before applying migrations.
+- `create`: Hooks to create the application schema after applying migrations.
 
 ## SQL hooks
 
 Hooks are defined as a list of files or plain SQL code to be executed. For example:
 
 ```yaml
-migration_hooks:
-  pre:
+application_hooks:
+  drop:
     - code: DROP VIEW IF EXISTS pum_test_app.some_view;
 
-  post:
-    - file: post/create_view.sql
+  create:
+    - file: create_app/create_view.sql
 ```
 
 ## Python hooks
@@ -32,16 +32,16 @@ You can use `pum.utils.execute_sql` to execute the SQL code without committing.
 The configuration is then:
 
 ```yaml
-migration_hooks:
-  pre:
-    - file: pre/drop_view.sql
+application_hooks:
+  drop:
+    - file: drop_app/drop_view.sql
 
-  post:
-    - file: post/create_schema.sql
-    - file: post/create_view.py
+  create:
+    - file: create_app/create_schema.sql
+    - file: create_app/create_view.py
 ```
 
-With `post/create_view.py`:
+With `create_app/create_view.py`:
 
 ```py
 from pirogue.utils import select_columns
@@ -85,7 +85,7 @@ class Hook(HookBase):
 > Local imports within the hook file are supported. The parent directory of the hook file is temporarily added to `sys.path` during execution, so you can use local imports in your hook scripts. Ensure your hook files and their dependencies are structured accordingly.
 
 
-## Data and application isoltion
+## Data and application isolation
 
 We recommend to isolate data (tables) from business logic (e.g., views, triggers) into distinct schemas for easier upgrades.
 This will facilitate the migrations but also the code management: you will not have to write diff files for views and triggers.
@@ -102,7 +102,7 @@ project/
 │   │   ├── 01_rename_column.sql
 │   │   └── 02_do_something_else.sql
 ├── app/
-│   ├── drop_views_and_triggers.sql
-│   └── create_views_and_triggers.sql
+│   ├── drop_app.sql
+│   └── create_app.sql
 └── .pum.yaml
 ```

docs/mkdocs.yml

@@ -72,7 +72,7 @@ nav:
       - ConfigModel: configuration/config_model.md
       - DependencyModel: configuration/dependency_model.md
       - HookModel: configuration/hook_model.md
-      - MigrationHooksModel: configuration/migration_hooks_model.md
+      - ApplicationHookModel: configuration/migration_hooks_model.md
       - ParameterDefinitionModel: configuration/parameter_definition_model.md
       - PermissionModel: configuration/permission_model.md
       - PumModel: configuration/pum_model.md

pum/cli.py

@@ -217,13 +217,13 @@ def create_parser() -> argparse.ArgumentParser:
         action="store_true",
     )
     parser_install.add_argument(
-        "--skip-pre-hooks",
-        help="Skip pre-hook handlers during installation.",
+        "--skip-drop-app",
+        help="Skip drop app handlers during installation.",
         action="store_true",
     )
     parser_install.add_argument(
-        "--skip-post-hooks",
-        help="Skip post-hook handlers during installation.",
+        "--skip-create-app",
+        help="Skip create app handlers during installation.",
         action="store_true",
     )
 
@@ -241,13 +241,13 @@ def create_parser() -> argparse.ArgumentParser:
         "--beta-testing", help="Install in beta testing mode.", action="store_true"
     )
     parser_upgrade.add_argument(
-        "--skip-pre-hooks",
-        help="Skip pre-hook handlers during upgrade.",
+        "--skip-drop-app",
+        help="Skip drop app handlers during upgrade.",
         action="store_true",
     )
     parser_upgrade.add_argument(
-        "--skip-post-hooks",
-        help="Skip post-hook handlers during upgrade.",
+        "--skip-create-app",
+        help="Skip create app handlers during upgrade.",
         action="store_true",
     )
 
@@ -397,8 +397,8 @@ def cli() -> int:  # noqa: PLR0912
                 roles=args.roles,
                 grant=args.grant,
                 beta_testing=args.beta_testing,
-                skip_pre_hooks=args.skip_pre_hooks,
-                skip_post_hooks=args.skip_post_hooks,
+                skip_drop_app=args.skip_drop_app,
+                skip_create_app=args.skip_create_app,
             )
             conn.commit()
             if args.demo_data:
@@ -407,8 +407,8 @@ def cli() -> int:  # noqa: PLR0912
                     connection=conn,
                     parameters=parameters,
                     grant=args.grant,
-                    skip_post_hooks=args.skip_post_hooks,
-                    skip_pre_hooks=args.skip_pre_hooks,
+                    skip_create_app=args.skip_create_app,
+                    skip_drop_app=args.skip_drop_app,
                 )
         elif args.command == "upgrade":
             upg = Upgrader(config=config)
@@ -417,8 +417,8 @@ def cli() -> int:  # noqa: PLR0912
                 parameters=parameters,
                 max_version=args.max_version,
                 beta_testing=args.beta_testing,
-                skip_pre_hooks=args.skip_pre_hooks,
-                skip_post_hooks=args.skip_post_hooks,
+                skip_drop_app=args.skip_drop_app,
+                skip_create_app=args.skip_create_app,
             )
         elif args.command == "role":
             if not args.action:

pum/config_model.py

@@ -8,7 +8,7 @@
 
 
 class PumCustomBaseModel(BaseModel):
-    model_config = ConfigDict(extra="forbid")
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
 
 
 class ParameterDefinitionModel(PumCustomBaseModel):
@@ -54,17 +54,27 @@ def validate_args(self):
         return self
 
 
-class MigrationHooksModel(PumCustomBaseModel):
+class ApplicationHookModel(PumCustomBaseModel):
     """
-    MigrationHooksModel holds the configuration for migration hooks.
+    ApplicationHookModel holds the configuration for application schema hooks.
 
     Attributes:
-        pre: List of pre-migration hooks.
-        post: List of post-migration hooks.
+        drop: Hooks to drop the application schema before applying migrations.
+        create: Hooks to create the application schema after applying migrations.
     """
 
-    pre: Optional[List[HookModel]] = []
-    post: Optional[List[HookModel]] = []
+    drop: Optional[List[HookModel]] = Field(default=[], alias="pre")
+    create: Optional[List[HookModel]] = Field(default=[], alias="post")
+
+    @model_validator(mode="before")
+    def handle_legacy_names(cls, values):
+        """Support legacy field names for backward compatibility."""
+        # If new names don't exist but old names do, use old names
+        if "drop" not in values and "pre" in values:
+            values["drop"] = values.pop("pre")
+        if "create" not in values and "post" in values:
+            values["create"] = values.pop("post")
+        return values
 
 
 class PumModel(PumCustomBaseModel):
@@ -187,15 +197,25 @@ class ConfigModel(PumCustomBaseModel):
     Attributes:
         pum: The PUM (Project Update Manager) configuration. Defaults to a new PumModel instance.
         parameters: List of parameter definitions. Defaults to an empty list.
-        migration_hooks: Configuration for migration hooks. Defaults to a new MigrationHooksModel instance.
+        application_hooks: Configuration for application schema hooks. Defaults to a new ApplicationHookModel instance.
         changelogs_directory: Directory path for changelogs. Defaults to "changelogs".
         roles: List of role definitions. Defaults to None.
     """
 
     pum: Optional[PumModel] = Field(default_factory=PumModel)
     parameters: Optional[List[ParameterDefinitionModel]] = []
-    migration_hooks: Optional[MigrationHooksModel] = Field(default_factory=MigrationHooksModel)
+    application_hooks: Optional[ApplicationHookModel] = Field(
+        default_factory=ApplicationHookModel, alias="migration_hooks"
+    )
     changelogs_directory: Optional[str] = "changelogs"
     roles: Optional[List[RoleModel]] = []
     demo_data: Optional[List[DemoDataModel]] = []
     dependencies: Optional[List[DependencyModel]] = []
+
+    @model_validator(mode="before")
+    def handle_legacy_field_names(cls, values):
+        """Support legacy field names for backward compatibility."""
+        # If new name doesn't exist but old name does, use old name
+        if "application_hooks" not in values and "migration_hooks" in values:
+            values["application_hooks"] = values.pop("migration_hooks")
+        return values

pum/pum_config.py

@@ -245,25 +245,25 @@ def role_manager(self) -> RoleManager:
             return RoleManager([])
         return RoleManager([role.model_dump() for role in self.config.roles])
 
-    def pre_hook_handlers(self) -> list[HookHandler]:
-        """Return the list of pre-migration hook handlers."""
+    def drop_app_handlers(self) -> list[HookHandler]:
+        """Return the list of drop app hook handlers."""
         return (
             [
                 HookHandler(base_path=self._base_path, **hook.model_dump())
-                for hook in self.config.migration_hooks.pre
+                for hook in self.config.application_hooks.drop
             ]
-            if self.config.migration_hooks.pre
+            if self.config.application_hooks.drop
             else []
         )
 
-    def post_hook_handlers(self) -> list[HookHandler]:
-        """Return the list of post-migration hook handlers."""
+    def create_app_handlers(self) -> list[HookHandler]:
+        """Return the list of create app hook handlers."""
         return (
             [
                 HookHandler(base_path=self._base_path, **hook.model_dump())
-                for hook in self.config.migration_hooks.post
+                for hook in self.config.application_hooks.create
             ]
-            if self.config.migration_hooks.post
+            if self.config.application_hooks.create
             else []
         )
 
@@ -311,10 +311,10 @@ def validate(self, install_dependencies: bool = False) -> None:
                 raise PumInvalidChangelog(f"Changelog `{changelog}` is invalid.") from e
 
         hook_handlers = []
-        if self.config.migration_hooks.pre:
-            hook_handlers.extend(self.pre_hook_handlers())
-        if self.config.migration_hooks.post:
-            hook_handlers.extend(self.post_hook_handlers())
+        if self.config.application_hooks.drop:
+            hook_handlers.extend(self.drop_app_handlers())
+        if self.config.application_hooks.create:
+            hook_handlers.extend(self.create_app_handlers())
         for hook_handler in hook_handlers:
             try:
                 hook_handler.validate(parameter_defaults)