pum 1.2.2__tar.gz → 1.3.0__tar.gz

{pum-1.2.2 → pum-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pum
-Version: 1.2.2
+Version: 1.3.0
 Summary: Pum stands for "Postgres Upgrades Manager". It is a Database migration management tool very similar to flyway-db or Liquibase, based on metadata tables.
 Author-email: Denis Rouzaud <denis@opengis.ch>
 License-Expression: GPL-2.0-or-later
@@ -32,6 +32,8 @@ Requires-Dist: flake8-isort; extra == "dev"
 Requires-Dist: flake8-print; extra == "dev"
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: nose2; extra == "dev"
+Provides-Extra: html
+Requires-Dist: Jinja2; extra == "html"
 Dynamic: license-file
 
 # PostgreSQL Upgrades Manager (PUM)
@@ -49,10 +51,12 @@ PUM (PostgreSQL Upgrades Manager) is a robust database migration management tool
 
 ## Key Features
 
+- **Flexible Database Connections**: Connect using PostgreSQL service names or direct connection strings (URI or parameters).
 - **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.
+- **Droppable & recreatable app with data isolation**: PUM supports a clean rebuild workflow where an application environment can be dropped and recreated deterministically using hooks (pre and post migration).
+
 
 ## Why PUM?
 

{pum-1.2.2 → pum-1.3.0}/README.md

@@ -13,10 +13,12 @@ PUM (PostgreSQL Upgrades Manager) is a robust database migration management tool
 
 ## Key Features
 
+- **Flexible Database Connections**: Connect using PostgreSQL service names or direct connection strings (URI or parameters).
 - **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.
+- **Droppable & recreatable app with data isolation**: PUM supports a clean rebuild workflow where an application environment can be dropped and recreated deterministically using hooks (pre and post migration).
+
 
 ## Why PUM?
 

pum-1.3.0/pum/__init__.py

@@ -0,0 +1,90 @@
+import importlib
+import logging
+from typing import Any, TYPE_CHECKING
+
+# Custom SQL logging level (more verbose than DEBUG)
+# Register with: logging.addLevelName(SQL, 'SQL')
+SQL = 5
+
+# Configure default logging for API usage (not CLI)
+# CLI will override this with its own configuration
+if not logging.getLogger().handlers:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(message)s",
+    )
+
+if TYPE_CHECKING:
+    from .changelog import Changelog
+    from .checker import Checker
+    from .dependency_handler import DependencyHandler
+    from .dumper import Dumper, DumpFormat
+    from .feedback import Feedback, LogFeedback, SilentFeedback
+    from .hook import HookBase, HookHandler
+    from .parameter import ParameterDefinition, ParameterType
+    from .pum_config import PumConfig
+    from .role_manager import Permission, PermissionType, Role, RoleManager
+    from .schema_migrations import SchemaMigrations
+    from .sql_content import SqlContent, CursorResult
+    from .upgrader import Upgrader
+
+__all__ = [
+    "Checker",
+    "Changelog",
+    "CursorResult",
+    "DependencyHandler",
+    "Dumper",
+    "DumpFormat",
+    "Feedback",
+    "HookBase",
+    "HookHandler",
+    "LogFeedback",
+    "ParameterDefinition",
+    "ParameterType",
+    "Permission",
+    "PermissionType",
+    "PumConfig",
+    "Role",
+    "RoleManager",
+    "SchemaMigrations",
+    "SilentFeedback",
+    "SQL",
+    "SqlContent",
+    "Upgrader",
+]
+
+
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    "Checker": ("pum.checker", "Checker"),
+    "Changelog": ("pum.changelog", "Changelog"),
+    "CursorResult": ("pum.sql_content", "CursorResult"),
+    "DependencyHandler": ("pum.dependency_handler", "DependencyHandler"),
+    "Dumper": ("pum.dumper", "Dumper"),
+    "DumpFormat": ("pum.dumper", "DumpFormat"),
+    "HookBase": ("pum.hook", "HookBase"),
+    "HookHandler": ("pum.hook", "HookHandler"),
+    "ParameterDefinition": ("pum.parameter", "ParameterDefinition"),
+    "ParameterType": ("pum.parameter", "ParameterType"),
+    "Permission": ("pum.role_manager", "Permission"),
+    "PermissionType": ("pum.role_manager", "PermissionType"),
+    "PumConfig": ("pum.pum_config", "PumConfig"),
+    "Role": ("pum.role_manager", "Role"),
+    "RoleManager": ("pum.role_manager", "RoleManager"),
+    "SchemaMigrations": ("pum.schema_migrations", "SchemaMigrations"),
+    "SqlContent": ("pum.sql_content", "SqlContent"),
+    "Upgrader": ("pum.upgrader", "Upgrader"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _LAZY_IMPORTS:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module_name, symbol_name = _LAZY_IMPORTS[name]
+    module = importlib.import_module(module_name)
+    value = getattr(module, symbol_name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(list(globals().keys()) + list(_LAZY_IMPORTS.keys())))

{pum-1.2.2 → pum-1.3.0}/pum/changelog.py

@@ -1,13 +1,21 @@
+import logging
 from os import listdir
 from os.path import basename
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 from packaging.version import parse as parse_version
 import psycopg
 
+from .schema_migrations import SchemaMigrations
 from .exceptions import PumInvalidChangelog, PumSqlError
 from .sql_content import SqlContent
 
+if TYPE_CHECKING:
+    from .feedback import Feedback
+
+logger = logging.getLogger(__name__)
+
 
 class Changelog:
     """This class represent a changelog directory.
@@ -82,6 +90,9 @@ class Changelog:
         connection: psycopg.Connection,
         parameters: dict | None = None,
         commit: bool = True,
+        schema_migrations: SchemaMigrations | None = None,
+        beta_testing: bool = False,
+        feedback: "Feedback | None" = None,
     ) -> list[Path]:
         """Apply a changelog
         This will execute all the files in the changelog directory.
@@ -94,18 +105,67 @@ class Changelog:
                 The parameters to pass to the SQL files
             commit: bool
                 If true, the transaction is committed. The default is true.
+            schema_migrations: SchemaMigrations | None
+                The SchemaMigrations instance to use to record the applied changelog.
+                If None, the changelog will not be recorded.
+            beta_testing: bool
+                If true, the changelog will be recorded as a beta testing version.
+            feedback: Feedback | None
+                Optional feedback object for progress reporting.
 
         Returns:
             list[Path]
                 The list of changelogs that were executed
 
         """
+        logger.info(f"Applying changelog version {self.version} from {self.dir}")
+
+        parameters_literals = SqlContent.prepare_parameters(parameters)
         files = self.files()
         for file in files:
+            if feedback:
+                feedback.increment_step()
+                feedback.report_progress(f"Executing {file.name}")
             try:
                 SqlContent(file).execute(
-                    connection=connection, commit=commit, parameters=parameters
+                    connection=connection, commit=commit, parameters=parameters_literals
                 )
             except PumSqlError as e:
                 raise PumSqlError(f"Error applying changelog {file}: {e}") from e
+        if schema_migrations:
+            schema_migrations.set_baseline(
+                connection=connection,
+                version=self.version,
+                beta_testing=beta_testing,
+                commit=commit,
+                changelog_files=[str(f) for f in files],
+                parameters=parameters,
+            )
         return files
+
+    def is_applied(
+        self,
+        connection: psycopg.Connection,
+        schema_migrations: SchemaMigrations,
+    ) -> bool:
+        """Check if the changelog has been applied.
+
+        Args:
+            connection: The database connection to use.
+        Returns:
+            bool: True if the changelog has been applied, False otherwise.
+        """
+        query = psycopg.sql.SQL("""
+                SELECT EXISTS (
+                    SELECT 1
+                    FROM {table}
+                    WHERE version = {version}
+                )
+                """)
+        parameters = {
+            "version": psycopg.sql.Literal(str(self.version)),
+            "table": schema_migrations.migration_table_identifier,
+        }
+        cursor = SqlContent(query).execute(connection, parameters=parameters)
+        result = cursor._pum_results[0] if cursor._pum_results else None
+        return result[0] if result else False