pum 1.2.2__py3-none-any.whl → 1.3.0__py3-none-any.whl

pum/cli.py

@@ -9,23 +9,36 @@ from pathlib import Path
 import psycopg
 
 from .checker import Checker
+from .report_generator import ReportGenerator
 from .pum_config import PumConfig
+from .connection import format_connection_string
 
 from .info import run_info
 from .upgrader import Upgrader
 from .parameter import ParameterType
 from .schema_migrations import SchemaMigrations
-from .dumper import DumpFormat
+from .dumper import DumpFormat, Dumper
+from . import SQL
 
 
 def setup_logging(verbosity: int = 0):
-    """Setup logging based on verbosity level (0=WARNING, 1=INFO, 2+=DEBUG) with colored output."""
-    level = logging.WARNING  # default
+    """Configure logging for the CLI.
 
-    if verbosity == 1:
-        level = logging.INFO
+    Args:
+        verbosity: Verbosity level (-1=quiet/WARNING, 0=INFO, 1=DEBUG, 2+=SQL).
+
+    """
+    # Register custom SQL log level
+    logging.addLevelName(SQL, "SQL")
+
+    if verbosity < 0:
+        level = logging.WARNING  # quiet mode
     elif verbosity >= 2:
+        level = SQL  # Most verbose - shows all SQL statements
+    elif verbosity >= 1:
         level = logging.DEBUG
+    else:
+        level = logging.INFO  # default
 
     class ColorFormatter(logging.Formatter):
         COLORS = {
@@ -33,6 +46,7 @@ def setup_logging(verbosity: int = 0):
             logging.WARNING: "\033[33m",  # Yellow
             logging.INFO: "\033[36m",  # Cyan
             logging.DEBUG: "\033[35m",  # Magenta
+            SQL: "\033[90m",  # Gray for SQL statements
         }
         RESET = "\033[0m"
 
@@ -54,108 +68,56 @@ def setup_logging(verbosity: int = 0):
 
 
 class Pum:
-    def __init__(self, pg_service: str, config: str | PumConfig = None) -> None:
+    def __init__(self, pg_connection: str, config: str | PumConfig = None) -> None:
         """Initialize the PUM class with a database connection and configuration.
 
         Args:
-            pg_service (str): The name of the postgres service (defined in pg_service.conf)
+            pg_connection (str): PostgreSQL service name or connection string.
+                Can be a service name (e.g., 'mydb') or a full connection string
+                (e.g., 'postgresql://user:pass@host/db' or 'host=localhost dbname=mydb').
             config (str | PumConfig): The configuration file path or a PumConfig object.
 
         """
-        self.pg_service = pg_service
+        self.pg_connection = pg_connection
 
         if isinstance(config, str):
             self.config = PumConfig.from_yaml(config)
         else:
             self.config = config
 
-    def run_check(
-        self,
-        pg_service1: str,
-        pg_service2: str,
-        ignore_list: list[str] | None,
-        exclude_schema: list[str] | None,
-        exclude_field_pattern: list[str] | None,
-        verbose_level: int = 1,
-        output_file: str | None = None,
-    ) -> bool:
-        """Run the check command.
 
-        Args:
-            pg_service1:
-                The name of the postgres service (defined in pg_service.conf)
-                related to the first db to be compared
-            pg_service2:
-                The name of the postgres service (defined in pg_service.conf)
-                related to the first db to be compared
-            ignore_list:
-                List of elements to be ignored in check (ex. tables, columns,
-                views, ...)
-            exclude_schema:
-                List of schemas to be ignored in check.
-            exclude_field_pattern:
-                List of field patterns to be ignored in check.
-            verbose_level:
-                verbose level, 0 -> nothing, 1 -> print first 80 char of each
-                difference, 2 -> print all the difference details
-            output_file:
-                a file path where write the differences
-
-        Returns:
-            True if no differences are found, False otherwise.
+def create_parser(
+    max_help_position: int | None = None, width: int | None = None
+) -> argparse.ArgumentParser:
+    """Create the main argument parser and all subparsers.
 
-        """
-        # self.__out("Check...")
-        verbose_level = verbose_level or 1
-        ignore_list = ignore_list or []
-        exclude_schema = exclude_schema or []
-        exclude_field_pattern = exclude_field_pattern or []
-        try:
-            checker = Checker(
-                pg_service1,
-                pg_service2,
-                exclude_schema=exclude_schema,
-                exclude_field_pattern=exclude_field_pattern,
-                ignore_list=ignore_list,
-                verbose_level=verbose_level,
-            )
-            result, differences = checker.run_checks()
+    Args:
+        max_help_position: Maximum help position for formatting.
+        width: Width for formatting.
 
-            if result:
-                self.__out("OK")
-            else:
-                self.__out("DIFFERENCES FOUND")
-
-            if differences:
-                if output_file:
-                    with open(output_file, "w") as f:
-                        for k, values in differences.items():
-                            f.write(k + "\n")
-                            f.writelines(f"{v}\n" for v in values)
-                else:
-                    for k, values in differences.items():
-                        print(k)
-                        for v in values:
-                            print(v)
-            return result
-
-        except psycopg.Error as e:
-            self.__out("ERROR")
-            self.__out(e.args[0] if e.args else str(e))
-            sys.exit(1)
-
-        except Exception as e:
-            self.__out("ERROR")
-            # if e.args is empty then use str(e)
-            self.__out(e.args[0] if e.args else str(e))
-            sys.exit(1)
+    Returns:
+        The fully configured argument parser.
 
+    """
+    if max_help_position is not None or width is not None:
 
-def create_parser() -> argparse.ArgumentParser:
-    """Creates the main parser with its sub-parsers"""
-    parser = argparse.ArgumentParser()
+        def formatter_class(prog):
+            return argparse.HelpFormatter(
+                prog, max_help_position=max_help_position or 40, width=width or 200
+            )
+    else:
+        formatter_class = argparse.HelpFormatter
+    parser = argparse.ArgumentParser(
+        prog="pum",
+        formatter_class=formatter_class,
+    )
     parser.add_argument("-c", "--config_file", help="set the config file. Default: .pum.yaml")
-    parser.add_argument("-s", "--pg-service", help="Name of the postgres service", required=True)
+    parser.add_argument(
+        "-p",
+        "--pg-connection",
+        help="PostgreSQL service name or connection string (e.g., 'mydb' or 'postgresql://user:pass@host/db')",
+        required=True,
+    )
 
     parser.add_argument(
         "-d", "--dir", help="Directory or URL of the module. Default: .", default="."
@@ -166,7 +128,14 @@ def create_parser() -> argparse.ArgumentParser:
         "--verbose",
         action="count",
         default=0,
-        help="Increase output verbosity (e.g. -v, -vv)",
+        help="Increase verbosity (-v for DEBUG, -vv for SQL statements)",
+    )
+
+    parser.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        help="Suppress info messages, only show warnings and errors",
     )
 
     version = importlib.metadata.version("pum")
@@ -182,10 +151,16 @@ def create_parser() -> argparse.ArgumentParser:
     )
 
     # Parser for the "info" command
-    parser_info = subparsers.add_parser("info", help="show info about schema migrations history.")  # NOQA
+    parser_info = subparsers.add_parser(  # NOQA
+        "info",
+        help="show info about schema migrations history.",
+        formatter_class=formatter_class,
+    )
 
     # Parser for the "install" command
-    parser_install = subparsers.add_parser("install", help="Installs the module.")
+    parser_install = subparsers.add_parser(
+        "install", help="Installs the module.", formatter_class=formatter_class
+    )
     parser_install.add_argument(
         "-p",
         "--parameter",
@@ -194,9 +169,9 @@ def create_parser() -> argparse.ArgumentParser:
         action="append",
     )
     parser_install.add_argument("--max-version", help="maximum version to install")
-    parser_install.add_argument("-r", "--roles", help="Create roles", action="store_true")
+    parser_install.add_argument("--skip-roles", help="Skip creating roles", action="store_true")
     parser_install.add_argument(
-        "-g", "--grant", help="Grant permissions to roles", action="store_true"
+        "--skip-grant", help="Skip granting permissions to roles", action="store_true"
     )
     parser_install.add_argument(
         "-d", "--demo-data", help="Load demo data with the given name", type=str, default=None
@@ -206,19 +181,70 @@ def create_parser() -> argparse.ArgumentParser:
         help="This will install the module in beta testing, meaning that it will not be possible to receive any future updates.",
         action="store_true",
     )
+    parser_install.add_argument(
+        "--skip-drop-app",
+        help="Skip drop app handlers during installation.",
+        action="store_true",
+    )
+    parser_install.add_argument(
+        "--skip-create-app",
+        help="Skip create app handlers during installation.",
+        action="store_true",
+    )
+
+    # Upgrade parser
+    parser_upgrade = subparsers.add_parser(
+        "upgrade", help="Upgrade the database.", formatter_class=formatter_class
+    )
+    parser_upgrade.add_argument(
+        "-p",
+        "--parameter",
+        nargs=2,
+        help="Assign variable for running SQL deltas. Format is name value.",
+        action="append",
+    )
+    parser_upgrade.add_argument("-u", "--max-version", help="maximum version to upgrade")
+    parser_upgrade.add_argument(
+        "--skip-grant", help="Skip granting permissions to roles", action="store_true"
+    )
+    parser_upgrade.add_argument(
+        "--beta-testing", help="Install in beta testing mode.", action="store_true"
+    )
+    parser_upgrade.add_argument(
+        "--force",
+        help="Allow upgrading a module installed in beta testing mode.",
+        action="store_true",
+    )
+    parser_upgrade.add_argument(
+        "--skip-drop-app",
+        help="Skip drop app handlers during upgrade.",
+        action="store_true",
+    )
+    parser_upgrade.add_argument(
+        "--skip-create-app",
+        help="Skip create app handlers during upgrade.",
+        action="store_true",
+    )
 
     # Role management parser
-    parser_role = subparsers.add_parser("role", help="manage roles in the database")
+    parser_role = subparsers.add_parser(
+        "role", help="manage roles in the database", formatter_class=formatter_class
+    )
     parser_role.add_argument(
         "action", choices=["create", "grant", "revoke", "drop"], help="Action to perform"
     )
 
     # Parser for the "check" command
-    parser_check = subparsers.add_parser(
-        "check", help="check the differences between two databases"
+    parser_checker = subparsers.add_parser(
+        "check", help="check the differences between two databases", formatter_class=formatter_class
     )
 
-    parser_check.add_argument(
+    parser_checker.add_argument(
+        "pg_connection_compared",
+        help="PostgreSQL service name or connection string for the database to compare against",
+    )
+
+    parser_checker.add_argument(
         "-i",
         "--ignore",
         help="Elements to be ignored",
@@ -235,20 +261,29 @@ def create_parser() -> argparse.ArgumentParser:
             "rules",
         ],
     )
-    parser_check.add_argument(
+    parser_checker.add_argument(
         "-N", "--exclude-schema", help="Schema to be ignored.", action="append"
     )
-    parser_check.add_argument(
+    parser_checker.add_argument(
         "-P",
         "--exclude-field-pattern",
         help="Fields to be ignored based on a pattern compatible with SQL LIKE.",
         action="append",
     )
 
-    parser_check.add_argument("-o", "--output_file", help="Output file")
+    parser_checker.add_argument("-o", "--output_file", help="Output file")
+    parser_checker.add_argument(
+        "-f",
+        "--format",
+        choices=["text", "html", "json"],
+        default="text",
+        help="Output format: text, html, or json. Default: text",
+    )
 
     # Parser for the "dump" command
-    parser_dump = subparsers.add_parser("dump", help="dump a Postgres database")
+    parser_dump = subparsers.add_parser(
+        "dump", help="dump a Postgres database", formatter_class=formatter_class
+    )
     parser_dump.add_argument(
         "-f",
         "--format",
@@ -264,7 +299,9 @@ def create_parser() -> argparse.ArgumentParser:
 
     # Parser for the "restore" command
     parser_restore = subparsers.add_parser(
-        "restore", help="restore a Postgres database from a dump file"
+        "restore",
+        help="restore a Postgres database from a dump file",
+        formatter_class=formatter_class,
     )
     parser_restore.add_argument("-x", help="ignore pg_restore errors", action="store_true")
     parser_restore.add_argument(
@@ -274,32 +311,63 @@ def create_parser() -> argparse.ArgumentParser:
 
     # Parser for the "baseline" command
     parser_baseline = subparsers.add_parser(
-        "baseline", help="Create upgrade information table and set baseline"
+        "baseline",
+        help="Create upgrade information table and set baseline",
+        formatter_class=formatter_class,
     )
     parser_baseline.add_argument(
         "-b", "--baseline", help="Set baseline in the format x.x.x", required=True
     )
+    parser_baseline.add_argument(
+        "--create-table",
+        help="Create the pum_migrations table if it does not exist",
+        action="store_true",
+    )
 
-    # Parser for the "upgrade" command
-    parser_upgrade = subparsers.add_parser("upgrade", help="upgrade db")
-    parser_upgrade.add_argument("-u", "--max-version", help="upper bound limit version")
-    parser_upgrade.add_argument(
+    # Parser for the "uninstall" command
+    parser_uninstall = subparsers.add_parser(
+        "uninstall",
+        help="Uninstall the module by executing uninstall hooks",
+        formatter_class=formatter_class,
+    )
+    parser_uninstall.add_argument(
         "-p",
         "--parameter",
         nargs=2,
-        help="Assign variable for running SQL deltas. Format is: name value.",
+        help="Assign variable for running SQL hooks. Format is name value.",
         action="append",
     )
+    parser_uninstall.add_argument(
+        "--force",
+        help="Skip confirmation prompt and proceed with uninstall",
+        action="store_true",
+        dest="force",
+    )
 
     return parser
 
 
 def cli() -> int:  # noqa: PLR0912
-    """Main function to run the command line interface."""
+    """Run the command line interface.
+
+    Returns:
+        Process exit code.
+
+    """
     parser = create_parser()
     args = parser.parse_args()
 
-    setup_logging(args.verbose)
+    # Validate mutually exclusive flags
+    if args.quiet and args.verbose:
+        parser.error("--quiet and --verbose are mutually exclusive")
+
+    # Set verbosity level (-1 for quiet, 0 for normal, 1+ for verbose)
+    if args.quiet:
+        verbosity = -1
+    else:
+        verbosity = args.verbose
+
+    setup_logging(verbosity)
     logger = logging.getLogger(__name__)
 
     # if no command is passed, print the help and exit
@@ -307,20 +375,72 @@ def cli() -> int:  # noqa: PLR0912
         parser.print_help()
         parser.exit()
 
+    # Handle check command separately (doesn't need db connection)
+    if args.command == "check":
+        exit_code = 0
+        checker = Checker(
+            args.pg_connection,
+            args.pg_connection_compared,
+            exclude_schema=args.exclude_schema or [],
+            exclude_field_pattern=args.exclude_field_pattern or [],
+            ignore_list=args.ignore or [],
+        )
+        report = checker.run_checks()
+        checker.conn1.close()
+        checker.conn2.close()
+
+        if report.passed:
+            logger.info("OK")
+        else:
+            logger.info("DIFFERENCES FOUND")
+
+        if args.format == "html":
+            html_report = ReportGenerator.generate_html(report)
+            if args.output_file:
+                with open(args.output_file, "w", encoding="utf-8") as f:
+                    f.write(html_report)
+                logger.info(f"HTML report written to {args.output_file}")
+            else:
+                print(html_report)
+        elif args.format == "json":
+            json_report = ReportGenerator.generate_json(report)
+            if args.output_file:
+                with open(args.output_file, "w", encoding="utf-8") as f:
+                    f.write(json_report)
+                logger.info(f"JSON report written to {args.output_file}")
+            else:
+                print(json_report)
+        else:
+            # Text output (backward compatible)
+            text_output = ReportGenerator.generate_text(report)
+            if args.output_file:
+                with open(args.output_file, "w") as f:
+                    f.write(text_output)
+            else:
+                print(text_output)
+
+        if not report.passed:
+            exit_code = 1
+
+        return exit_code
+
+    validate = args.command not in ("info", "baseline")
     if args.config_file:
-        config = PumConfig.from_yaml(args.config_file, install_dependencies=True)
+        config = PumConfig.from_yaml(args.config_file, validate=validate, install_dependencies=True)
     else:
-        config = PumConfig.from_yaml(Path(args.dir) / ".pum.yaml", install_dependencies=True)
+        config = PumConfig.from_yaml(
+            Path(args.dir) / ".pum.yaml", validate=validate, install_dependencies=True
+        )
 
-    with psycopg.connect(f"service={args.pg_service}") as conn:
+    with psycopg.connect(format_connection_string(args.pg_connection)) as conn:
         # Check if the connection is successful
         if not conn:
-            logger.error(f"Could not connect to the database using service: {args.pg_service}")
+            logger.error(f"Could not connect to the database: {args.pg_connection}")
             sys.exit(1)
 
         # Build parameters dict for install and upgrade commands
         parameters = {}
-        if args.command in ("install", "upgrade"):
+        if args.command in ("install", "upgrade", "uninstall"):
             for p in args.parameter or ():
                 param = config.parameter(p[0])
                 if not param:
@@ -338,7 +458,6 @@ def cli() -> int:  # noqa: PLR0912
                     raise ValueError(f"Unsupported parameter type for {p[0]}: {param.type}")
             logger.debug(f"Parameters: {parameters}")
 
-        pum = Pum(args.pg_service, config)
         exit_code = 0
 
         if args.command == "info":
@@ -349,13 +468,34 @@ def cli() -> int:  # noqa: PLR0912
                 connection=conn,
                 parameters=parameters,
                 max_version=args.max_version,
-                roles=args.roles,
-                grant=args.grant,
+                roles=not args.skip_roles,
+                grant=not args.skip_grant,
                 beta_testing=args.beta_testing,
+                skip_drop_app=args.skip_drop_app,
+                skip_create_app=args.skip_create_app,
             )
             conn.commit()
             if args.demo_data:
-                upg.install_demo_data(name=args.demo_data, connection=conn, parameters=parameters)
+                upg.install_demo_data(
+                    name=args.demo_data,
+                    connection=conn,
+                    parameters=parameters,
+                    grant=not args.skip_grant,
+                    skip_create_app=args.skip_create_app,
+                    skip_drop_app=args.skip_drop_app,
+                )
+        elif args.command == "upgrade":
+            upg = Upgrader(config=config)
+            upg.upgrade(
+                connection=conn,
+                parameters=parameters,
+                max_version=args.max_version,
+                grant=not args.skip_grant,
+                beta_testing=args.beta_testing,
+                force=args.force,
+                skip_drop_app=args.skip_drop_app,
+                skip_create_app=args.skip_create_app,
+            )
         elif args.command == "role":
             if not args.action:
                 logger.error(
@@ -374,28 +514,51 @@ def cli() -> int:  # noqa: PLR0912
                 else:
                     logger.error(f"Unknown action: {args.action}")
                     exit_code = 1
-        elif args.command == "check":
-            success = pum.run_check(
-                args.pg_service1,
-                args.pg_service2,
-                ignore_list=args.ignore,
-                exclude_schema=args.exclude_schema,
-                exclude_field_pattern=args.exclude_field_pattern,
-                verbose_level=args.verbose_level,
-                output_file=args.output_file,
-            )
-            if not success:
-                exit_code = 1
         elif args.command == "dump":
-            pass
+            dumper = Dumper(args.pg_connection, args.file)
+            dumper.pg_dump(
+                exclude_schema=args.exclude_schema or [],
+                format=args.format,
+            )
+            logger.info(f"Database dumped to {args.file}")
         elif args.command == "restore":
-            pum.run_restore(args.pg_service, args.file, args.x, args.exclude_schema)
+            dumper = Dumper(args.pg_connection, args.file)
+            try:
+                dumper.pg_restore(exclude_schema=args.exclude_schema or [])
+                logger.info(f"Database restored from {args.file}")
+            except Exception as e:
+                if not args.x:
+                    raise
+                logger.warning(f"Restore completed with errors (ignored): {e}")
         elif args.command == "baseline":
+            sm = SchemaMigrations(config=config)
+            if not sm.exists(connection=conn):
+                if args.create_table:
+                    sm.create(connection=conn)
+                    logger.info("Created pum_migrations table.")
+                else:
+                    logger.error(
+                        "pum_migrations table does not exist. Use --create-table to create it."
+                    )
+                    exit_code = 1
+                    return exit_code
             SchemaMigrations(config=config).set_baseline(connection=conn, version=args.baseline)
 
-        elif args.command == "upgrade":
-            # TODO
-            logger.error("Upgrade is not implemented yet")
+        elif args.command == "uninstall":
+            # Confirmation prompt unless --force is used
+            if not args.force:
+                logger.warning(
+                    "⚠️  WARNING: This will execute uninstall hooks which may drop schemas and data!"
+                )
+                response = input("Are you sure you want to proceed? (yes/no): ").strip().lower()
+                if response not in ("yes", "y"):
+                    logger.info("Uninstall cancelled.")
+                    return 0
+
+            upg = Upgrader(config=config)
+            upg.uninstall(connection=conn, parameters=parameters)
+            logger.info("Uninstall completed successfully.")
+
         else:
             logger.error(f"Unknown command: {args.command}")
             logger.error("Use -h or --help for help.")