dblift 2.1.0__tar.gz → 2.2.0__tar.gz

{dblift-2.1.0 → dblift-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dblift
-Version: 2.1.0
+Version: 2.2.0
 Summary: A database migration tool that supports multiple databases with native Python drivers
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers

{dblift-2.1.0 → dblift-2.2.0}/cli/_command_handlers.py

@@ -43,7 +43,9 @@ if _builtin_conflicts:
 _COMMAND_HANDLERS.update(_extension_handlers)
 del _extension_handlers, _builtin_conflicts
 
-_AVAILABLE_COMMANDS = list(_COMMAND_HANDLERS.keys()) + ["db"] + list(load_terminal_commands())
+_AVAILABLE_COMMANDS = (
+    list(_COMMAND_HANDLERS.keys()) + ["db", "config"] + list(load_terminal_commands())
+)
 
 
 def execute_single_command(

{dblift-2.1.0 → dblift-2.2.0}/cli/_config_helpers.py

@@ -189,12 +189,45 @@ def _build_args_namespace(
     return args, unknown_args
 
 
+# Default config filenames searched in the current working directory when no
+# --config is given, in precedence order. Lets `dblift <command>` run without an
+# explicit --config when a config file sits in the project root, matching the
+# convention of peer tools (Alembic's alembic.ini, Flyway's flyway.conf).
+_DEFAULT_CONFIG_NAMES: Tuple[str, ...] = ("dblift.yaml", "dblift.yml")
+
+
+def _discover_default_config(log: Any = None) -> Optional[str]:
+    """Return the path to a default config file in the cwd, or None.
+
+    Searches the current working directory for the filenames in
+    :data:`_DEFAULT_CONFIG_NAMES` and returns the first match. Returns ``None``
+    when no default config is present, preserving the existing behaviour for
+    pure ``--db-url`` workflows.
+    """
+    cwd = Path.cwd()
+    for name in _DEFAULT_CONFIG_NAMES:
+        candidate = cwd / name
+        if candidate.is_file():
+            if log:
+                log.debug(f"Using discovered config file: {candidate}")
+            return str(candidate)
+    return None
+
+
 def _load_and_merge_config(args: argparse.Namespace, log: Any) -> Any:
     """Load configuration and merge database overrides from CLI arguments.
 
     Returns:
         Loaded and merged config object
     """
+    # Auto-discover a config file in the cwd when the user passed neither
+    # --config nor --db-url, so `dblift <command>` works from a project that has
+    # a dblift.yaml without forcing an explicit --config on every invocation.
+    if not getattr(args, "config", None) and not getattr(args, "database_url", None):
+        discovered = _discover_default_config(log)
+        if discovered:
+            args.config = discovered
+
     try:
         config = load_config(args.config, args)
     except (

{dblift-2.1.0 → dblift-2.2.0}/cli/_parser_setup.py

@@ -106,6 +106,53 @@ def _make_history_table_parent() -> argparse.ArgumentParser:
     return p
 
 
+def _add_registry_flags(parser: argparse.ArgumentParser) -> None:
+    """Emit a --flag for every registry property that lacks one.
+
+    Skips properties that are cli_only, cli_exempt, nested (database.*), or
+    already covered by a legacy flag recorded in cli_aliases. Ensures any NEW
+    persistent property added to the registry automatically gets a CLI flag,
+    so the CLI surface can never silently drift from config/env again.
+    """
+    from config.property_registry import PROPERTY_REGISTRY
+
+    # Collect option strings across the WHOLE tree (root + every subparser), not
+    # just the root parser. Many registry properties (e.g. --tags,
+    # --target-version, --snapshot-table) intentionally live only on specific
+    # subcommands; a root-only ``existing`` set would treat them as missing and
+    # emit a duplicate root flag, colliding with the subparser dest. This helper
+    # therefore runs AFTER subparsers are registered so the tree walk sees them.
+    existing: set[str] = set()
+
+    def _collect(p: argparse.ArgumentParser) -> None:
+        for action in p._actions:
+            existing.update(action.option_strings)
+            choices = getattr(action, "choices", None)
+            if isinstance(choices, dict):
+                for sub in choices.values():
+                    if isinstance(sub, argparse.ArgumentParser):
+                        _collect(sub)
+
+    _collect(parser)
+    for spec in PROPERTY_REGISTRY:
+        if spec.cli_only or spec.cli_exempt or "." in spec.name:
+            continue
+        if spec.cli_aliases:
+            continue  # legacy flag (e.g. --table, --strict) already provides the surface
+        if spec.cli in existing:
+            continue
+        if spec.type == "bool":
+            parser.add_argument(
+                spec.cli, dest=spec.name, action="store_true", default=None, help=spec.help
+            )
+        elif spec.type == "int":
+            parser.add_argument(spec.cli, dest=spec.name, type=int, default=None, help=spec.help)
+        elif spec.type == "float":
+            parser.add_argument(spec.cli, dest=spec.name, type=float, default=None, help=spec.help)
+        else:
+            parser.add_argument(spec.cli, dest=spec.name, default=None, help=spec.help)
+
+
 def _make_snapshot_table_parent() -> argparse.ArgumentParser:
     """Parent parser for explicit snapshot storage commands."""
     p = argparse.ArgumentParser(add_help=False)
@@ -307,6 +354,11 @@ def create_parser(
         ),
     )
     parser.add_argument("--dry-run", action="store_true", help="Dry run mode")
+    parser.add_argument(
+        "--installed-by",
+        dest="installed_by",
+        help="Value recorded in the installed_by column (default: database username)",
+    )
     parser.add_argument("--log-dir", default="logs", help="Log directory")
     parser.add_argument("--log-format", default="text", help="Log format (text, json, html)")
     parser.add_argument(
@@ -404,7 +456,21 @@ def create_parser(
     db_parser = subparsers.add_parser("db", help="Database utility commands")
     db_subparsers = db_parser.add_subparsers(dest="db_command", required=True)
     setup_db_utils_parser(db_subparsers)
+    # Configuration introspection: `dblift config --list` prints every persistent
+    # property and its three surfaces (config key / env var / CLI flag). Distinct
+    # from the global `--config <path>` option — a subcommand named ``config`` and
+    # an optional ``--config`` flag do not collide in argparse.
+    config_parser = subparsers.add_parser("config", help="Inspect dblift configuration")
+    config_parser.add_argument(
+        "--list",
+        action="store_true",
+        help="List all properties and how to set them (config key / env var / CLI flag)",
+    )
     import_module("cli.extensions").load_command_extensions(parser)
+    # Emit registry-derived flags LAST, after every subparser (built-in and
+    # extension) is registered, so the tree walk in _add_registry_flags can see
+    # subcommand-only flags and skip them instead of shadowing them on the root.
+    _add_registry_flags(parser)
     if suppress_errors:
         all_subparsers = [
             migrate_parser,

dblift-2.2.0/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""First-party CLI command handlers that own their own dispatch."""

dblift-2.2.0/cli/commands/config_command.py

@@ -0,0 +1,48 @@
+"""``dblift config --list`` — print every persistent property and its surfaces."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from config.property_registry import PROPERTY_REGISTRY, PropertySpec
+from core.logger.console import render_records_table
+
+
+def _cli_display(spec: PropertySpec) -> str:
+    """The real CLI flag for a property: '(none)' if cli-exempt, the legacy
+    alias if one is registered, else the derived flag."""
+    if spec.cli_exempt:
+        return "(none)"
+    if spec.cli_aliases:
+        return str(spec.cli_aliases[0])
+    return spec.cli
+
+
+def build_property_table() -> List[Dict[str, str]]:
+    """Return one row per registry property with its config key, env var, CLI flag, and default."""
+    rows: List[Dict[str, str]] = []
+    for spec in PROPERTY_REGISTRY:
+        rows.append(
+            {
+                "name": spec.name,
+                "config": spec.name,
+                "env": spec.env,
+                "cli": _cli_display(spec),
+                "default": "" if spec.default is None else str(spec.default),
+            }
+        )
+    return rows
+
+
+def run_config_command(args: Any) -> int:
+    """Print the property/env/CLI surface table for ``dblift config --list``; return 0."""
+    rows = build_property_table()
+    table = render_records_table(
+        [("PROPERTY", "left"), ("ENV VAR", "left"), ("CLI FLAG", "left")],
+        [[r["name"], r["env"], r["cli"]] for r in rows],
+        title="dblift configuration properties",
+    )
+    print(
+        table
+    )  # lint: allow-print  config --list self-documentation (pre-CommandOutput short-circuit)
+    return 0

{dblift-2.1.0 → dblift-2.2.0}/cli/main.py

@@ -102,6 +102,16 @@ _GLOBAL_ONLY_ARGS: List[str] = [
     "--quiet",
     "-q",
     "--no-progress",
+    # Root-only value flags surfaced from the PropertySpec registry
+    # (installed_by is added directly; max_snapshots is generated by
+    # _add_registry_flags). They live only on the root parser, so — like the
+    # other root-only value flags above — they must be classified global or the
+    # argv preprocessor relocates them past the subcommand token and the
+    # subparser rejects them as "unrecognized arguments". Covered by
+    # tests/unit/cli/test_global_only_args_completeness.py.
+    "--installed-by",
+    "--max-snapshots",
+    "--snapshot-table",
 ]
 
 # Tool-level flag aliases for subcommands that take their own version-like
@@ -227,6 +237,15 @@ def _parse_argv_and_load_config(argv: List[str]) -> _CliContext:
     if not commands and hasattr(args, "command"):
         commands = [args.command]
 
+    # `dblift config --list` is offline self-documentation: it reads only the
+    # property registry, so it short-circuits here — before any config/db load —
+    # exactly like the `db` subcommand path below. Listing is the command's only
+    # behaviour today, so it runs whether or not --list was passed.
+    if commands and commands[0] == "config":
+        from cli.commands.config_command import run_config_command
+
+        sys.exit(run_config_command(args))
+
     log = LogFactory.get_log("Dblift")
     parser = create_parser()
     # Validate log format before any config load so bogus --log-format fails with argparse
@@ -316,7 +335,6 @@ def _dispatch_command(ctx: _CliContext, command_output: CommandOutput) -> int:
         ctx.log.debug(f"Using placeholders: {placeholders}")
 
     ctx.config.journal_enabled = True
-    ctx.config.journal_dir = None
     if getattr(ctx.args, "strict", False):
         ctx.config.strict_mode = True
         ctx.log.info(
@@ -382,7 +400,6 @@ def _dispatch_command(ctx: _CliContext, command_output: CommandOutput) -> int:
                 recursive=recursive,
                 placeholders=placeholders,
                 dir_recursive_map=dir_recursive_map,
-                license_tier=_resolve_license_tier(ctx.args),
             )
             if not success:
                 any_command_failed = True

{dblift-2.1.0 → dblift-2.2.0}/config/dblift_config.py

@@ -285,7 +285,6 @@ class DbliftConfig:
         1  # Maximum number of snapshots to keep (oldest are deleted when limit exceeded)
     )
     journal_enabled: bool = True
-    journal_dir: Optional[str] = None
 
     # Error handling and retry configuration
     error_handling_enabled: bool = True
@@ -572,8 +571,8 @@ class DbliftConfig:
         migrations_directories = migrations.get("directories", [])
         migrations_recursive = migrations.get("recursive", True)
 
-        # Journal settings are always in-memory only - ignore journal_dir if set in config files
-        # journal_enabled defaults to True, journal_dir defaults to None (will be enforced in cli/main.py)
+        # Journal settings are always in-memory only
+        # journal_enabled defaults to True
         config = cls(
             database=database_config,
             migrations=MigrationsConfig(
@@ -614,8 +613,6 @@ class DbliftConfig:
             log_level=data.get("log_level"),
             secrets=secrets_config,
         )
-        # Explicitly ensure journal_dir is None (journal is always in-memory only)
-        config.journal_dir = None
         config.log_dir = root_log_dir
         return config
 
@@ -699,7 +696,11 @@ class DbliftConfig:
         # cannot pollute or shadow legitimate config fields.
         #
         # Names whose env-var suffix differs from the config field name
-        _DB_ALIASES: Dict[str, str] = {"USER": "username", "SESSION_VARS": "session_variables"}
+        _DB_ALIASES: Dict[str, str] = {
+            "USER": "username",
+            "USERNAME": "username",
+            "SESSION_VARS": "session_variables",
+        }
         # Suffixes that require structured (JSON / k=v CSV) parsing into a dict
         _STRUCTURED = {"OPTIONS", "SESSION_VARS", "EXTRA_PARAMS", "PROPERTIES"}
         # Suffixes whose value must be coerced to int
@@ -719,6 +720,7 @@ class DbliftConfig:
             | {
                 "URL",
                 "USER",
+                "USERNAME",
                 "PASSWORD",
                 "SCHEMA",
                 "HOST",
@@ -776,19 +778,23 @@ class DbliftConfig:
         config: Dict[str, Any] = {}
         if db:
             config["database"] = db
-        if env.get("DBLIFT_SNAPSHOT_TABLE"):
-            config["snapshot_table"] = env["DBLIFT_SNAPSHOT_TABLE"]
-        if env.get("DBLIFT_HISTORY_TABLE"):
-            config["history_table"] = env["DBLIFT_HISTORY_TABLE"]
-        if env.get("DBLIFT_MAX_SNAPSHOTS"):
-            try:
-                config["max_snapshots"] = int(env["DBLIFT_MAX_SNAPSHOTS"])
-            except ValueError:
-                if diagnostics is not None:
-                    diagnostics.invalid_int_vars.append("DBLIFT_MAX_SNAPSHOTS")
-                pass  # Ignore invalid values
-        if env.get("DBLIFT_CLEAN_DISABLED"):
-            config["clean_disabled"] = env["DBLIFT_CLEAN_DISABLED"].lower() in ("1", "true", "yes")
+
+        from config.property_registry import PROPERTY_REGISTRY
+
+        for spec in PROPERTY_REGISTRY:
+            if spec.cli_only or "." in spec.name:
+                continue  # nested database.* fields are handled by the DBLIFT_DB_* loop above
+            raw = env.get(spec.env)
+            if not raw:
+                continue
+            if spec.coerce is not None:
+                try:
+                    config[spec.name] = spec.coerce(raw)
+                except (ValueError, TypeError):
+                    if diagnostics is not None:
+                        diagnostics.invalid_int_vars.append(spec.env)
+            else:
+                config[spec.name] = raw
         return config
 
     @classmethod
@@ -849,34 +855,16 @@ class DbliftConfig:
         if db_cfg:
             config["database"] = db_cfg
 
-        for key in (
-            "snapshot_table",
-            "history_table",
-            "max_snapshots",
-            "baseline_version",
-            "target_version",
-            "dry_run",
-            "undo",
-            "installed_by",
-            "mark_as_executed",
-            "strict_mode",
-            "clean_disabled",
-            "journal_enabled",
-            "error_handling_enabled",
-            "max_retries",
-            "retry_delay",
-            "retry_backoff",
-            "retry_jitter",
-            "retryable_error_categories",
-            "tags",
-            "exclude_tags",
-            "versions",
-            "exclude_versions",
-            "log_file",
-            "log_dir",
-            "log_format",
-            "log_level",
-        ):
+        from config.property_registry import PROPERTY_REGISTRY
+
+        # Registry covers the persistent scalar properties; these three are
+        # arg-only keys not modeled in the registry (undo is subcommand-driven,
+        # journal_enabled/retryable_error_categories are non-scalar/internal).
+        _arg_only_keys = ("undo", "journal_enabled", "retryable_error_categories")
+        registry_keys = [
+            spec.name for spec in PROPERTY_REGISTRY if not spec.cli_only and "." not in spec.name
+        ]
+        for key in (*registry_keys, *_arg_only_keys):
             if key in args and args[key] not in (None, ""):
                 config[key] = args[key]
 
@@ -1019,9 +1007,6 @@ class DbliftConfig:
         if self.placeholders:
             result["placeholders"] = self.placeholders
 
-        if self.journal_dir:
-            result["journal_dir"] = self.journal_dir
-
         if self.log_dir:
             result["log_dir"] = self.log_dir
 

dblift-2.2.0/config/property_registry.py

@@ -0,0 +1,135 @@
+"""Single source of truth for every persistent dblift property.
+
+Each :class:`PropertySpec` mechanically derives its environment variable and
+CLI flag from its dotted config name, so a property can never be added to one
+surface and silently missing from another. See
+``tests/unit/config/test_property_parity.py`` (added in a later task) for the
+invariant that enforces this across ``from_env_dict`` / ``from_args_dict`` /
+``to_dict`` / the CLI parser.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, List, Optional
+
+
+def env_name(name: str) -> str:
+    """Derive the env var: ``database.username`` -> ``DBLIFT_DB_USERNAME``."""
+    if name.startswith("database."):
+        name = "db_" + name[len("database.") :]
+    return "DBLIFT_" + name.replace(".", "_").upper()
+
+
+def cli_flag(name: str) -> str:
+    """Derive the CLI flag: ``database.username`` -> ``--db-username``."""
+    if name.startswith("database."):
+        name = "db_" + name[len("database.") :]
+    return "--" + name.replace(".", "_").replace("_", "-")
+
+
+@dataclass(frozen=True)
+class PropertySpec:
+    name: str  # dotted config key; "database.<field>" for nested db config
+    type: str  # "str" | "int" | "float" | "bool" | "dict" | "list"
+    default: object = None
+    cli_only: bool = False  # runtime meta-flags (version/quiet/...) — no env/config
+    cli_exempt: bool = False  # has env+config but intentionally no CLI flag
+    cli_aliases: tuple = ()  # legacy flag names that already provide this CLI surface
+    coerce: Optional[Callable[[str], object]] = None
+    help: str = ""
+
+    @property
+    def env(self) -> str:
+        return env_name(self.name)
+
+    @property
+    def cli(self) -> str:
+        return cli_flag(self.name)
+
+
+def _bool(v: str) -> bool:
+    return v.lower() in ("1", "true", "yes")
+
+
+# NOTE: keep this list the ONLY place persistent properties are declared.
+# Structured db fields (extra_params, properties, options, session_variables)
+# and CosmosDB-specific fields keep their existing bespoke env/arg parsing and
+# are intentionally EXCLUDED here.
+PROPERTY_REGISTRY: List[PropertySpec] = [
+    # --- dblift-managed tables ---
+    PropertySpec(
+        "history_table",
+        "str",
+        "dblift_schema_history",
+        cli_aliases=("--table",),
+        help="dblift schema-history table name",
+    ),
+    PropertySpec(
+        "snapshot_table",
+        "str",
+        "dblift_schema_snapshots",
+        help="dblift schema-snapshots table name",
+    ),
+    PropertySpec("max_snapshots", "int", 1, coerce=int, help="Max snapshots to retain"),
+    # --- audit / execution ---
+    PropertySpec(
+        "installed_by",
+        "str",
+        None,
+        help="Value recorded in the installed_by column (default: db username)",
+    ),
+    PropertySpec("baseline_version", "str", None),
+    PropertySpec("target_version", "str", None),
+    PropertySpec("mark_as_executed", "bool", False, coerce=_bool),
+    PropertySpec("strict_mode", "bool", False, coerce=_bool, cli_aliases=("--strict",)),
+    PropertySpec("clean_disabled", "bool", True, coerce=_bool),
+    PropertySpec("dry_run", "bool", False, coerce=_bool),
+    # --- migration selection ---
+    PropertySpec("tags", "str", None),
+    PropertySpec("exclude_tags", "str", None),
+    PropertySpec("versions", "str", None),
+    PropertySpec("exclude_versions", "str", None),
+    # --- retry / error handling (config+env, no CLI flag) ---
+    PropertySpec("error_handling_enabled", "bool", True, coerce=_bool, cli_exempt=True),
+    PropertySpec("max_retries", "int", 3, coerce=int, cli_exempt=True),
+    PropertySpec("retry_delay", "float", 1.0, coerce=float, cli_exempt=True),
+    PropertySpec("retry_backoff", "float", 2.0, coerce=float, cli_exempt=True),
+    PropertySpec("retry_jitter", "float", 0.2, coerce=float, cli_exempt=True),
+    # --- logging ---
+    PropertySpec("log_level", "str", None),
+    PropertySpec("log_format", "str", None),
+    PropertySpec("log_file", "str", None),
+    PropertySpec("log_dir", "str", None),
+    # --- database connection (nested under database.*) ---
+    # NOTE: the env/args generators skip dotted (database.*) names. These fields
+    # are read by the pre-existing DBLIFT_DB_* machinery in DbliftConfig
+    # (_DB_ALIASES / _ALLOWED), which also handles the structured/aliased/CosmosDB
+    # cases the registry does not model. Listing them here is NOT redundant: the
+    # parity tests validate each one's surfaces, so adding a new database.* field
+    # without a corresponding DBLIFT_DB_* allowlist entry fails CI loudly rather
+    # than silently dropping the surface. Drift is detected, not eliminated, for
+    # these fields.
+    PropertySpec("database.url", "str", ""),
+    PropertySpec("database.type", "str", None, cli_exempt=True),
+    PropertySpec("database.username", "str", ""),
+    PropertySpec("database.password", "str", ""),
+    PropertySpec("database.schema", "str", ""),
+    PropertySpec("database.host", "str", None, cli_exempt=True),
+    PropertySpec("database.port", "int", None, coerce=int, cli_exempt=True),
+    PropertySpec("database.database", "str", None, cli_exempt=True),
+    PropertySpec("database.connection_timeout", "int", 30, coerce=int, cli_exempt=True),
+]
+
+
+def spec_for(name: str) -> Optional[PropertySpec]:
+    """Return the :class:`PropertySpec` for ``name``, or ``None`` if unknown.
+
+    Runtime-only meta flags (``--version``, ``--quiet``, ``--config`` …) are not
+    persistent properties and are intentionally absent from the registry, so
+    ``spec_for("version")`` returns ``None`` by design.
+    """
+    for spec in PROPERTY_REGISTRY:
+        if spec.name == name:
+            return spec
+    return None