dbly 0.2.0__tar.gz → 0.3.0__tar.gz

dbly-0.3.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+ko_fi: angrydata

dbly-0.3.0/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+All notable changes to `dbly` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] — 2026-07-21
+
+### Added
+
+- **Plan against the working tree.** `dbly plan --worktree` (alias `--dirty`) and
+  `dbly check --worktree` diff the *working directory* — including uncommitted edits and
+  untracked new object files — instead of a git ref, for the fast edit→plan loop. Preview
+  only; `apply` still requires a real committed ref for the ledger.
+- **Git-style ref decoration.** `dbly status` and the plan header now show the tag/branch
+  names pointing at a SHA next to it — e.g. `deployed ref: v0.1, main (a712b631)`. The
+  ledger still stores only the SHA (for stable diffs); the names are resolved at display time.
+
+### Fixed
+
+- **Column type changes are now detected.** A changed column type (e.g. Oracle `NUMBER` →
+  `NUMBER(10)`) previously produced "nothing to do" — the diff matched columns by name only.
+  It now emits an `ALTER TABLE … MODIFY`/`ALTER COLUMN` step (flagged destructive, never
+  auto-applied) with a data-compatibility warning. Comparison is precision/scale-aware and
+  normalizes introspection noise (e.g. SQL Server `COLLATE`) to avoid false positives.
+- **`check` no longer reports live Oracle objects as "missing".** The Oracle adapter now
+  resolves its `default_schema` to the connected user and carries the owner on introspected
+  objects, so drift keys align with the desired side (previously the owner was dropped on the
+  live side, so every object looked missing even right after a successful `apply`).
+
+### Changed
+
+- The plan output now surfaces each step's **note inline** (e.g. *"NOT NULL without default
+  on existing table — unsafe"*), so *why* a step is flagged is visible without cross-checking
+  the warnings block.
+
+## [0.2.0] — 2026-06-28
+
+### Added
+
+- **Explicit, run-once migrations.** Drop ordered SQL scripts in `migrations/` (`0001_…sql`)
+  for changes the additive diff cannot do safely — renaming a column, type changes with data
+  transformation, backfills. Each is tracked by id in the `dbly_state` ledger and runs
+  exactly once.
+- On **upgrade**, pending migrations run *before* the object reconciliation, so they reshape
+  the schema first. On a **fresh database** they are *baselined* (recorded, not run) since the
+  canonical object files already describe the end state.
+
+### Changed
+
+- A table touched by a pending migration **defers its additive diff** for that deploy, so an
+  explicit rename no longer collides with an auto-generated `ADD COLUMN`.
+- `migrations/` files are excluded from object and drift discovery (they are imperative
+  scripts, not declarative objects).
+
+## [0.1.0] — 2026-06-27
+
+### Added
+
+- **Indexes and sequences as first-class managed objects.** Correct identity (index name +
+  indexed-table schema), dependency-safe ordering (sequences → tables → indexes), and
+  create-if-missing handling (no more erroneous re-apply of non-idempotent
+  `CREATE INDEX`/`CREATE SEQUENCE`).
+- **Live inventory introspection** across tables, views, functions, procedures, triggers,
+  indexes and sequences for all four engines, with a canonical source hash for procedural
+  objects.
+- **Real drift detection in `dbly check`** — reports missing (in repo, not in DB), orphaned
+  (`--orphans`), table column drift, and advisory definition drift; schema-normalized so an
+  unqualified repo object matches the engine's implicit schema.
+
+## [0.0.1] — 2026-06-27
+
+### Added
+
+- Initial release. **State-based, cross-engine database deployment** (PostgreSQL, SQL Server,
+  Oracle, SQLite), git-driven and parser-assisted (sqlglot).
+- `plan` / `apply` workflow with additive table diffs generated from
+  `CREATE TABLE IF NOT EXISTS` (destructive changes flagged, never auto-applied).
+- `plan --sql` — exports a self-contained SQL script for a hand/offline deploy.
+- `dbly init` — privileged greenfield groundwork (`CREATE DATABASE`/roles/extensions).
+- Pre-/post-deploy hooks accepting `.sql` and `.py` (configurable interpreter, e.g. ArcPy).
+- Connection profiles (DBFit-compatible `connection.properties`) with `${ENV}` placeholders
+  for CI/CD.
+- CI and PyPI publish workflows (trusted publishing).
+
+[Unreleased]: https://github.com/angrydat/dbly/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/angrydat/dbly/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/angrydat/dbly/compare/v0.0.1...v0.1.0
+[0.0.1]: https://github.com/angrydat/dbly/releases/tag/v0.0.1

{dbly-0.2.0 → dbly-0.3.0}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: dbly
-Version: 0.2.0
+Version: 0.3.0
 Summary: State-based, cross-engine database deployment — git-driven, parser-assisted, SQL-first.
 Project-URL: Homepage, https://angrydata.info/dbly
 Project-URL: Repository, https://github.com/angrydat/dbly
 Project-URL: Issues, https://github.com/angrydat/dbly/issues
+Project-URL: Changelog, https://github.com/angrydat/dbly/blob/main/CHANGELOG.md
 Author-email: Jürgen Zornig <info@angrydata.info>
 License: MIT
 Keywords: ci-cd,database,deployment,git,migration,oracle,postgres,schema,sql,sqlite,sqlserver,state-based

dbly-0.3.0/TODO.md

@@ -0,0 +1,70 @@
+# dbly — TODO / Ideen-Backlog
+
+Kurzliste möglicher Verbesserungen, entstanden aus dem Vergleich mit **Atlas**
+(atlasgo.io). Das sind Funktionen, die Atlas (teils nur in der kommerziellen
+Pro-Edition) bietet und die dbly aktuell **nicht** hat — als Anregung, nicht als
+Roadmap. dbly-Stärken (frei, MIT, Oracle/MSSQL nativ, `.py`-Hooks, `plan --sql`)
+bleiben der Ausgangspunkt.
+
+## Migrations- & Sicherheits-Analyse
+- **Migration-Linting / Analyzer**: destruktive/riskante Schritte erkennen und
+  warnen bzw. blocken (Atlas `migrate lint`). dbly kennt bisher nur additiv vs.
+  destruktiv + `--allow-destructive`.
+- **Custom Schema Rules / Policies** (z. B. „jede Tabelle braucht PK", Namens-
+  konventionen, Boolean = NUMBER(1) CHECK (0,-1) erzwingen).
+- **Pre-Migration-Checks** (Vorbedingungen prüfen, z. B. Spalte leer vor NOT NULL).
+- **PII-/Security-as-Code**: Spalten als sensibel markieren; RLS deklarativ.
+
+## Sichtbarkeit
+- **ERD / Schema-Visualisierung** + Auto-Doku aus dem Objektmodell.
+- **Schema-Registry** / zentrale „source of truth" mit Versionsvergleich über
+  Umgebungen hinweg.
+- **Kontinuierliches Drift-Monitoring**: dbly hat `check` on-demand; es fehlt ein
+  laufendes/alarmierendes Monitoring.
+- ~~**Ref-Dekoration in `status` / Plan-Header** (Komfort)~~ ✅ **erledigt (0.3.0)**:
+  `status` und der Plan-Header zeigen jetzt Tag-/Branch-Namen neben dem SHA
+  (`deployed ref: v0.1, main (9ff5e440)`), aufgelöst via `git tag/branch --points-at`.
+  Der Ledger speichert weiterhin nur den SHA.
+
+## Autoren-Erlebnis
+- Zusätzliche **Schema-Sprache (HCL o. ä.)** und/oder **ORM-Loader** — DB-agnostische
+  Definition neben plain SQL.
+- **Testing-Framework** für Schema/Objekte (Atlas `atlas test`).
+- **Interaktive Migrations / Checkpoints** für lange Migrationsketten.
+- ~~**Plan gegen den Working-Tree** (uncommittete Änderungen)~~ ✅ **erledigt (0.3.0)**:
+  `dbly plan --worktree` (Alias `--dirty`) und `dbly check --worktree` planen/prüfen
+  den Arbeitsstand inkl. ungetrackter neuer Objektdateien. Preview-only — `apply`
+  braucht weiterhin einen committeten Ref für den Ledger.
+
+## Integration
+- Breitere fertige **CI-Rezepte** (GitLab, Azure DevOps, CircleCI) — aktuell nur
+  GH-Actions/Bitbucket-Beispiele.
+- **Terraform-Provider / K8s-Operator** (GitOps).
+- **Rollout-/Approval-Flow** (Freigabe vor Apply in Prod).
+
+## Bekannte Design-Frage (aus dem MA31-PoC)
+- Im Planner werden **Tabellen in Changeset-Reihenfolge** emittiert;
+  `topological_order` wird nur auf *replaceable* (Views/Functions) angewandt. Bei
+  Inline-FKs zwischen Tabellen ist auf einem frischen Ziel die Anlege-Reihenfolge
+  dann nicht FK-sicher — prüfen, ob Tabellen ebenfalls topologisch sortiert werden
+  sollten (oder ob der Adapter das per retry-until-stable abfängt).
+
+## Bugs (aus MA31-PoC, Oracle)
+
+- ~~**Spalten-Typänderung wird nicht erkannt.**~~ ✅ **erledigt (0.3.0)**: Der
+  Spalten-Diff verglich nur den Namen; `NUMBER` → `NUMBER(10)` blieb unbemerkt. Jetzt
+  wird bei geändertem Typ ein `ALTER TABLE … MODIFY`/`ALTER COLUMN`-Schritt erzeugt
+  (als `destructive` markiert, nie auto-appliziert, mit Datenkompatibilitäts-Warnung).
+  Der Vergleich ist Precision/Scale-bewusst (`NUMBER(10)` ≡ `NUMBER(10,0)`) und
+  normalisiert Introspektions-Rauschen (z. B. SQL-Server `COLLATE`) gegen False Positives.
+- ~~**ADD COLUMN fälschlich als „destructive" klassifiziert.**~~ ✅ **geklärt (0.3.0)**:
+  `TESTFELD` war `NOT NULL` **ohne** Default — die `destructive`-Einstufung ist damit
+  korrekt (kann auf einer befüllten Tabelle nicht sicher hinzugefügt werden). Verbessert:
+  der Grund (*„NOT NULL without default … — unsafe"*) wird jetzt als Hinweis direkt am
+  Plan-Schritt angezeigt, nicht nur im Warnungsblock.
+- ~~**`check` meldet vorhandene Objekte als „missing".**~~ ✅ **erledigt (0.3.0)**:
+  Ursache war eine asymmetrische Key-Normalisierung — der Oracle-Adapter setzte kein
+  `default_schema` und ließ den Owner in `inventory()` weg, sodass die Live-Keys
+  (`table:<name>`) nicht zu den Desired-Keys (`table:dbb.<name>`) passten. Der Adapter
+  löst `default_schema` jetzt zum verbundenen `USER` auf und führt den Owner mit; beide
+  Seiten normalisieren identisch.

{dbly-0.2.0 → dbly-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dbly"
-version = "0.2.0"
+version = "0.3.0"
 description = "State-based, cross-engine database deployment — git-driven, parser-assisted, SQL-first."
 readme = "README.md"
 license = { text = "MIT" }
@@ -54,6 +54,7 @@ all = ["oracledb>=2.0", "pymssql>=2.3"]
 Homepage = "https://angrydata.info/dbly"
 Repository = "https://github.com/angrydat/dbly"
 Issues = "https://github.com/angrydat/dbly/issues"
+Changelog = "https://github.com/angrydat/dbly/blob/main/CHANGELOG.md"
 
 [project.scripts]
 dbly = "dbly.cli:main"

{dbly-0.2.0 → dbly-0.3.0}/src/dbly/__init__.py

@@ -4,4 +4,4 @@ git (what changed) + sqlglot (what it is) + live introspection (what's really th
 See CONCEPT.md for the design rationale.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{dbly-0.2.0 → dbly-0.3.0}/src/dbly/adapters/base.py

@@ -71,6 +71,15 @@ class Adapter(abc.ABC):
         dialect-agnostic and delegates the rendering here.
         """
 
+    @abc.abstractmethod
+    def modify_column_sql(self, table: ObjectId, col: Column) -> str:
+        """Generate the ``ALTER TABLE … <MODIFY|ALTER COLUMN>`` that changes a column's type.
+
+        Oracle uses ``MODIFY``; Postgres uses ``ALTER COLUMN … TYPE``; T-SQL uses
+        ``ALTER COLUMN``. SQLite cannot change a column's type in place and returns a
+        commented no-op (a type change there needs a manual table rebuild).
+        """
+
     # --- execution ---------------------------------------------------------------------
     @abc.abstractmethod
     def apply(self, statements: list[str]) -> None:

{dbly-0.2.0 → dbly-0.3.0}/src/dbly/adapters/mssql.py

@@ -125,6 +125,10 @@ class MssqlAdapter(Adapter):
             parts.append(f"DEFAULT {col.default}")
         return " ".join(parts) + ";"
 
+    def modify_column_sql(self, table: ObjectId, col: Column) -> str:
+        # T-SQL ALTER COLUMN preserves nullability unless restated; type only here.
+        return f"ALTER TABLE {table} ALTER COLUMN {col.name} {col.type};"
+
     def apply(self, statements: list[str]) -> None:
         with self.engine.begin() as conn:
             for stmt in statements:

{dbly-0.2.0 → dbly-0.3.0}/src/dbly/adapters/oracle.py

@@ -89,6 +89,22 @@ class OracleAdapter(Adapter):
         # unquoted Oracle identifiers are upper-cased on storage
         return ident.upper() if ident else ident
 
+    @property
+    def default_schema(self) -> str | None:  # type: ignore[override]
+        """The connected user — Oracle's implicit schema for unqualified objects.
+
+        Resolved from the live session (``SELECT USER``) and cached. Drift matching uses this
+        so a repo object under folder ``dbb`` aligns with the live ``DBB``-owned object;
+        without it every object read back by ``inventory()`` looked "missing" (owner dropped
+        on one side of the key). Same source as ``inventory()``'s ``owner = USER`` filter.
+        """
+        cached = getattr(self, "_ds_cache", None)
+        if cached is None:
+            with self.engine.connect() as conn:
+                cached = conn.exec_driver_sql("SELECT USER FROM dual").scalar()
+            self._ds_cache = cached
+        return cached
+
     def table_exists(self, schema: str | None, name: str) -> bool:
         return inspect(self.engine).has_table(self._norm(name), schema=self._norm(schema))
 
@@ -139,6 +155,7 @@ class OracleAdapter(Adapter):
             "('FUNCTION','PROCEDURE','TRIGGER','PACKAGE','PACKAGE BODY','TYPE') "
             "ORDER BY name, type, line"
         )
+        owner = self.default_schema  # objects are filtered by owner = USER — carry it on the id
         found: dict[str, LiveObject] = {}
         src_text: dict[str, list[str]] = {}
         with self.engine.connect() as conn:
@@ -146,13 +163,13 @@ class OracleAdapter(Adapter):
                 kind = self._TYPEMAP.get(otype)
                 if kind is None:
                     continue
-                obj = LiveObject(kind, ObjectId(None, name))
+                obj = LiveObject(kind, ObjectId(owner, name))
                 found[obj.key()] = obj
             for name, otype, line in conn.execute(sources):
                 kind = self._TYPEMAP.get(otype)
                 if kind is None:
                     continue
-                key = LiveObject(kind, ObjectId(None, name)).key()
+                key = LiveObject(kind, ObjectId(owner, name)).key()
                 src_text.setdefault(key, []).append(line or "")
         for key, lines in src_text.items():
             if key in found:
@@ -167,6 +184,9 @@ class OracleAdapter(Adapter):
             parts.append("NOT NULL")
         return " ".join(parts) + ";"
 
+    def modify_column_sql(self, table: ObjectId, col: Column) -> str:
+        return f"ALTER TABLE {table} MODIFY {col.name} {col.type};"
+
     def apply(self, statements: list[str]) -> None:
         # No transactional rollback (DDL auto-commits). Sequential; commit covers any DML.
         with self.engine.connect() as conn:

{dbly-0.2.0 → dbly-0.3.0}/src/dbly/adapters/postgres.py

@@ -111,6 +111,9 @@ class PostgresAdapter(Adapter):
             parts.append(f"DEFAULT {col.default}")
         return " ".join(parts) + ";"
 
+    def modify_column_sql(self, table: ObjectId, col: Column) -> str:
+        return f"ALTER TABLE {table} ALTER COLUMN {col.name} TYPE {col.type};"
+
     def apply(self, statements: list[str]) -> None:
         # transactional DDL → one atomic transaction
         with self.engine.begin() as conn:

{dbly-0.2.0 → dbly-0.3.0}/src/dbly/adapters/sqlite.py

@@ -80,6 +80,14 @@ class SqliteAdapter(Adapter):
             parts.append(f"DEFAULT {col.default}")
         return " ".join(parts) + ";"
 
+    def modify_column_sql(self, table: ObjectId, col: Column) -> str:
+        # SQLite cannot change a column's type in place — a rebuild is required. Emit a
+        # commented no-op so the (destructive, never auto-applied) step documents the limit.
+        return (
+            f"-- SQLite cannot ALTER COLUMN {table.name}.{col.name} to {col.type} "
+            "in place; rebuild the table manually."
+        )
+
     def apply(self, statements: list[str]) -> None:
         with self.engine.begin() as conn:
             for stmt in statements:

{dbly-0.2.0 → dbly-0.3.0}/src/dbly/cli.py

@@ -21,7 +21,7 @@ from dbly.engine import detect_dialect
 from dbly.parsing import sqlglot_dialect
 from dbly.planner import build_plan
 from dbly.model import Plan, Severity
-from dbly.repo import Repo
+from dbly.repo import WORKTREE, Repo
 
 app = typer.Typer(
     name="dbly",
@@ -48,13 +48,32 @@ def _main(
     pass
 
 
-def _make_plan(repo_path: Path, target: str, from_ref: Optional[str], to_ref: str) -> Plan:
+def _decorations(repo_path: Path, plan: Plan) -> dict[str, str]:
+    """Map each real ref in the plan to its git tag/branch names (for the plan header)."""
+    try:
+        repo = Repo(repo_path)
+    except ValueError:
+        return {}
+    out: dict[str, str] = {}
+    for ref in {plan.from_ref, plan.to_ref}:
+        if not ref or ref == WORKTREE:
+            continue
+        names = repo.ref_names(ref)
+        if names:
+            out[ref] = ", ".join(names)
+    return out
+
+
+def _make_plan(
+    repo_path: Path, target: str, from_ref: Optional[str], to_ref: str,
+    *, worktree: bool = False,
+) -> Plan:
     repo = Repo(repo_path)
     cfg = resolve_target(target)
     dialect = sqlglot_dialect(detect_dialect(cfg))
     adapter = get_adapter(cfg)
     try:
-        resolved_to = repo.resolve_ref(to_ref)
+        resolved_to = repo.resolve_ref(WORKTREE if worktree else to_ref)
         if from_ref is not None:
             resolved_from = repo.resolve_ref(from_ref)
         else:
@@ -80,10 +99,15 @@ def plan(
     sql: Optional[Path] = typer.Option(
         None, "--sql", help="write an executable SQL script for a hand/offline deploy."
     ),
+    worktree: bool = typer.Option(
+        False, "--worktree", "--dirty",
+        help="plan against the working tree (uncommitted + untracked object files), "
+             "not a git ref — for the fast edit→plan loop.",
+    ),
 ) -> None:
     """Compute and show the deployment plan."""
-    plan_obj = _make_plan(repo_path, target, from_ref, to)
-    report.render_plan(plan_obj, console)
+    plan_obj = _make_plan(repo_path, target, from_ref, to, worktree=worktree)
+    report.render_plan(plan_obj, console, ref_names=_decorations(repo_path, plan_obj))
     if out:
         out.write_text(report.plan_to_yaml(plan_obj), encoding="utf-8")
         console.print(f"\n[dim]plan (YAML) written to {out}[/dim]")
@@ -123,7 +147,7 @@ def apply(
     else:
         plan_obj = _make_plan(repo_path, target, from_ref, to)
 
-    report.render_plan(plan_obj, console)
+    report.render_plan(plan_obj, console, ref_names=_decorations(repo_path, plan_obj))
 
     destructive = [s for s in plan_obj.steps if s.severity is Severity.DESTRUCTIVE]
     if destructive and not allow_destructive:
@@ -203,12 +227,15 @@ def bootstrap(
 ) -> None:
     """Install into an empty database (no baseline — full apply)."""
     plan_obj = _make_plan(repo_path, target, None, to)
-    report.render_plan(plan_obj, console)
+    report.render_plan(plan_obj, console, ref_names=_decorations(repo_path, plan_obj))
     console.print("\n[dim]review, then run `dbly apply` to execute.[/dim]")
 
 
 @app.command()
-def status(target: str = typer.Option(..., "--target")) -> None:
+def status(
+    target: str = typer.Option(..., "--target"),
+    repo_path: Path = typer.Option(Path("."), "--repo", help="repository root (for ref names)."),
+) -> None:
     """Show the deployed ref recorded on the target."""
     cfg = resolve_target(target)
     adapter = get_adapter(cfg)
@@ -216,10 +243,17 @@ def status(target: str = typer.Option(..., "--target")) -> None:
         ref = adapter.get_deployed_ref()
     finally:
         adapter.dispose()
-    if ref:
-        console.print(f"deployed ref: [cyan]{ref}[/cyan]")
-    else:
+    if not ref:
         console.print("[yellow]no deploy recorded — database is unmanaged or empty.[/yellow]")
+        return
+    try:
+        names = Repo(repo_path).ref_names(ref)
+    except ValueError:
+        names = []  # not a git repo — SHA only
+    if names:
+        console.print(f"deployed ref: [cyan]{', '.join(names)}[/cyan] [dim]({ref[:8]})[/dim]")
+    else:
+        console.print(f"deployed ref: [cyan]{ref}[/cyan]")
 
 
 @app.command()
@@ -230,6 +264,10 @@ def check(
     orphans: bool = typer.Option(
         False, "--orphans", help="also report objects in the DB but not in the repo."
     ),
+    worktree: bool = typer.Option(
+        False, "--worktree", "--dirty",
+        help="compare the working tree (uncommitted + untracked) against the DB, not a git ref.",
+    ),
 ) -> None:
     """Detect drift: compare the desired state at <to> against the live database."""
     repo = Repo(repo_path)
@@ -239,7 +277,8 @@ def check(
     try:
         rep = drift.compute_drift(
             repo, adapter,
-            to_ref=repo.resolve_ref(to), dialect=dialect, include_orphans=orphans,
+            to_ref=repo.resolve_ref(WORKTREE if worktree else to),
+            dialect=dialect, include_orphans=orphans,
         )
     finally:
         adapter.dispose()

{dbly-0.2.0 → dbly-0.3.0}/src/dbly/parsing.py

@@ -11,6 +11,7 @@ applied verbatim per dialect by the adapter.
 from __future__ import annotations
 
 import hashlib
+import re
 from pathlib import Path
 
 import sqlglot
@@ -193,6 +194,41 @@ def desired_columns(sql: str, *, dialect: str | None = None) -> list[Column]:
     return columns
 
 
+_NUMERIC_TYPES = {"NUMBER", "NUMERIC", "DECIMAL", "DEC"}
+
+
+def canonical_type(type_str: str) -> str:
+    """Normalize a column type for cross-boundary comparison (desired vs. introspected).
+
+    The desired side is rendered by sqlglot (e.g. ``NUMBER(10)``); the actual side comes from
+    SQLAlchemy introspection (e.g. ``NUMBER(10, 0)``). Whitespace/case and an *omitted numeric
+    scale* are normalized so semantically-equal types compare equal — while a genuine
+    precision/scale change (``NUMBER`` → ``NUMBER(10)``) is preserved.
+
+    Honest scope: this is a string-level normalizer, not a type system. Exotic spellings that
+    differ across the sqlglot↔SQLAlchemy boundary may still compare unequal; a resulting
+    MODIFY step is flagged destructive (never auto-applied) and carries a warning, so a false
+    positive surfaces as a reviewable note rather than silent data loss.
+    """
+    s = " ".join(type_str.strip().upper().split())
+    # Drop introspection decorations that carry no shape info (e.g. SQL Server appends
+    # `COLLATE "SQL_Latin1_General_CP1_CI_AS"` to reflected string types).
+    s = re.split(r"\s+COLLATE\s+", s, maxsplit=1)[0].strip()
+    m = re.match(r"^([A-Z0-9_ ]+?)\s*\(([^)]*)\)\s*$", s)
+    if not m:
+        return s.replace(" ", "")
+    base = m.group(1).strip().replace(" ", "")
+    params = [p.strip() for p in m.group(2).split(",") if p.strip()]
+    if base in _NUMERIC_TYPES and len(params) == 1:
+        params.append("0")  # NUMBER(p) ≡ NUMBER(p,0) — scale defaults to 0
+    return f"{base}({','.join(params)})"
+
+
+def types_differ(desired: str, actual: str) -> bool:
+    """Whether a declared (desired) column type differs from the live (actual) one."""
+    return canonical_type(desired) != canonical_type(actual)
+
+
 def topological_order(objects: list[ParsedObject]) -> list[ParsedObject]:
     """Order replaceable objects so dependencies come first (CONCEPT.md §8).
 

{dbly-0.2.0 → dbly-0.3.0}/src/dbly/planner.py

@@ -174,6 +174,28 @@ def _plan_table(adapter: Adapter, plan: Plan, obj: ParsedObject, dialect: str |
                 )
             )
 
+    # type changes: column present on both sides, but the declared type differs. Never
+    # auto-applied (a narrowing/incompatible change can truncate or fail) — flagged for review.
+    for col in desired:
+        actual_col = actual_by_key.get(col.key())
+        if actual_col is None or not parsing.types_differ(col.type, actual_col.type):
+            continue
+        plan.steps.append(
+            Step(
+                title=f"modify column {obj.id}.{col.name} type → {col.type}",
+                object_id=obj.id,
+                kind=ObjectKind.TABLE,
+                severity=Severity.DESTRUCTIVE,
+                sql=adapter.modify_column_sql(obj.id, col),
+                source_file=obj.source_file,
+                note=f"type change {actual_col.type} → {col.type} — may truncate/convert data",
+            )
+        )
+        plan.warnings.append(
+            f"{obj.id}.{col.name}: type change {actual_col.type} → {col.type} is not "
+            "auto-applied — review for data compatibility, then use --allow-destructive"
+        )
+
     # destructive: columns present in actual, gone from desired
     for col in actual:
         if col.key() not in desired_by_key:

{dbly-0.2.0 → dbly-0.3.0}/src/dbly/repo.py

@@ -17,6 +17,7 @@ from dbly.model import ChangeType
 
 _SQL_SUFFIXES = {".sql", ".tbl", ".vw", ".prc", ".fnc", ".pkg", ".trg", ".typ", ".ddl"}
 MIGRATIONS_DIR = "migrations"  # run-once scripts — not declarative objects
+WORKTREE = "WORKTREE"  # sentinel `to_ref`: plan/check against the working tree, not a git ref
 
 
 @dataclass(slots=True)
@@ -61,15 +62,39 @@ class Repo:
         """A deployable declarative object file (SQL, not a migration, not ignored)."""
         return self._is_sql(rel) and not self._is_migration(rel) and not self.is_ignored(rel)
 
+    def _untracked_files(self) -> list[Path]:
+        """New files in the working tree not yet added to git (``git status`` "??")."""
+        raw = self._git("ls-files", "--others", "--exclude-standard", "-z")
+        return [Path(n) for n in filter(None, raw.split("\0"))]
+
+    def _worktree_paths(self) -> list[Path]:
+        """Every file in the working tree: tracked (``ls-files``) + untracked new files."""
+        raw = self._git("ls-files", "-z")
+        tracked = [Path(n) for n in filter(None, raw.split("\0"))]
+        return tracked + self._untracked_files()
+
     def changed_files(self, from_ref: str | None, to_ref: str) -> list[FileChange]:
         """Files changed between two refs (or the full tree at ``to_ref`` for bootstrap)."""
         if from_ref is None:
             return [FileChange(p, ChangeType.ADDED) for p in self.list_files(to_ref)]
+        if to_ref == WORKTREE:
+            # `git diff <from>` (no second ref) diffs the ref against the working tree
+            # (staged + unstaged tracked changes); untracked new files are added separately.
+            changes = self._parse_name_status(
+                self._git("diff", "--name-status", "-z", from_ref)
+            )
+            known = {c.path for c in changes}
+            for p in self._untracked_files():
+                if self._is_object(p) and p not in known:
+                    changes.append(FileChange(p, ChangeType.ADDED))
+            return changes
         raw = self._git("diff", "--name-status", "-z", f"{from_ref}..{to_ref}")
         return self._parse_name_status(raw)
 
     def list_files(self, ref: str) -> list[Path]:
         """All deployable declarative object files present at ``ref`` (excludes migrations)."""
+        if ref == WORKTREE:
+            return [p for p in self._worktree_paths() if self._is_object(p)]
         raw = self._git("ls-tree", "-r", "--name-only", "-z", ref)
         return [Path(n) for n in filter(None, raw.split("\0")) if self._is_object(Path(n))]
 
@@ -78,11 +103,12 @@ class Repo:
 
         Id is the filename; order is lexicographic, so prefix files ``0001_…`` / a timestamp.
         """
-        raw = self._git("ls-tree", "-r", "--name-only", "-z", ref)
-        out = [
-            Path(n) for n in filter(None, raw.split("\0"))
-            if self._is_migration(Path(n)) and Path(n).suffix.lower() == ".sql"
-        ]
+        if ref == WORKTREE:
+            names = self._worktree_paths()
+        else:
+            raw = self._git("ls-tree", "-r", "--name-only", "-z", ref)
+            names = [Path(n) for n in filter(None, raw.split("\0"))]
+        out = [p for p in names if self._is_migration(p) and p.suffix.lower() == ".sql"]
         return [(p.name, p) for p in sorted(out, key=lambda p: p.as_posix())]
 
     def _parse_name_status(self, raw: str) -> list[FileChange]:
@@ -111,12 +137,33 @@ class Repo:
         """Resolve a symbolic ref (HEAD, a tag, a branch) to its immutable commit SHA.
 
         The ledger and plan headers store the SHA, not ``HEAD`` — so a later ``--from``
-        diff is stable regardless of where HEAD has since moved.
+        diff is stable regardless of where HEAD has since moved. The ``WORKTREE`` sentinel
+        has no SHA and is returned unchanged.
         """
+        if ref == WORKTREE:
+            return WORKTREE
         return self._git("rev-parse", ref).strip()
 
+    def ref_names(self, sha: str) -> list[str]:
+        """Tag and branch names pointing exactly at ``sha`` — for git-style plan/status
+        decorations (e.g. ``v0.1, main``). Display-only; the ledger still stores the SHA."""
+        names: list[str] = []
+        try:
+            names += [n for n in self._git("tag", "--points-at", sha).split() if n]
+            names += [
+                n for n in self._git(
+                    "branch", "--points-at", sha, "--format=%(refname:short)"
+                ).split() if n
+            ]
+        except subprocess.CalledProcessError:
+            return []
+        seen: set[str] = set()
+        return [n for n in names if not (n in seen or seen.add(n))]
+
     def read_at(self, ref: str, rel: Path) -> str:
         """File content at a given ref (the *desired* state)."""
+        if ref == WORKTREE:
+            return (self.root / rel).read_text(encoding="utf-8")
         return self._git("show", f"{ref}:{rel.as_posix()}")
 
     def schema_for(self, rel: Path) -> str | None:

{dbly-0.2.0 → dbly-0.3.0}/src/dbly/report.py

@@ -14,10 +14,23 @@ from rich.table import Table
 from dbly.model import Migration, ObjectId, ObjectKind, Plan, Severity, Step
 
 
-def render_plan(plan: Plan, console: Console) -> None:
+def _decorate_ref(ref: str | None, ref_names: dict[str, str] | None) -> str:
+    """Render a ref for the plan header: git-style ``<names> (<short-sha>)`` when known."""
+    if not ref:
+        return "∅"
+    if ref == "WORKTREE":
+        return "working tree"
+    if ref_names and ref_names.get(ref):
+        return f"{ref_names[ref]} ({ref[:8]})"
+    return ref
+
+
+def render_plan(
+    plan: Plan, console: Console, *, ref_names: dict[str, str] | None = None
+) -> None:
     console.print(
         f"[bold]Plan[/bold] for [cyan]{plan.target}[/cyan]  "
-        f"{plan.from_ref or '∅'} → {plan.to_ref}"
+        f"{_decorate_ref(plan.from_ref, ref_names)} → {_decorate_ref(plan.to_ref, ref_names)}"
     )
     if not plan.steps and not plan.warnings and not plan.migrations and not plan.baselined:
         console.print("[green]nothing to do — target is up to date[/green]")
@@ -38,11 +51,14 @@ def render_plan(plan: Plan, console: Console) -> None:
         table.add_column("step")
         for i, step in enumerate(plan.steps, 1):
             sev_style = "red" if step.severity is Severity.DESTRUCTIVE else "green"
+            title = step.title
+            if step.note:  # surface *why* a step is flagged (e.g. NOT NULL without default)
+                title += f"\n[dim]↳ {step.note}[/dim]"
             table.add_row(
                 str(i),
                 f"[{sev_style}]{step.severity.value}[/{sev_style}]",
                 step.kind.value,
-                step.title,
+                title,
             )
         console.print(table)
 

{dbly-0.2.0 → dbly-0.3.0}/tests/test_integration.py

@@ -268,3 +268,103 @@ def test_init_runs_ordered_multistatement_scripts(tmp_path: Path):
     assert adapter.table_exists(None, "meta")
     assert adapter.table_exists(None, "audit")
     adapter.dispose()
+
+
+def test_type_change_produces_destructive_modify_step(tmp_path: Path):
+    from dbly.repo import WORKTREE  # noqa: F401 — import guard; used indirectly below
+    repo_root = tmp_path / "db"
+    repo_root.mkdir()
+    _init_repo(repo_root)
+    (repo_root / "kunde.tbl").write_text(
+        "CREATE TABLE IF NOT EXISTS kunde (id INTEGER, code VARCHAR(10));", encoding="utf-8"
+    )
+    ref1 = _commit(repo_root, "v1")
+
+    db = tmp_path / "types.db"
+    adapter = SqliteAdapter(ConnectionConfig(environment="sqlite", service=str(db)))
+    repo = Repo(repo_root)
+    plan1 = build_plan(repo, adapter, from_ref=None, to_ref=ref1,
+                       target="sqlite", dialect="sqlite")
+    adapter.apply([s.sql for s in plan1.steps])
+    adapter.record_deploy(ref1, [])
+
+    # widen code VARCHAR(10) -> VARCHAR(20): a type change, must surface as a MODIFY step
+    (repo_root / "kunde.tbl").write_text(
+        "CREATE TABLE IF NOT EXISTS kunde (id INTEGER, code VARCHAR(20));", encoding="utf-8"
+    )
+    ref2 = _commit(repo_root, "v2")
+    plan2 = build_plan(repo, adapter, from_ref=ref1, to_ref=ref2,
+                       target="sqlite", dialect="sqlite")
+    mod = [s for s in plan2.steps if "modify column" in s.title]
+    assert len(mod) == 1
+    assert mod[0].severity is Severity.DESTRUCTIVE            # never auto-applied
+    assert "code" in mod[0].title
+    assert "→" in mod[0].note and "10" in mod[0].note and "20" in mod[0].note
+    adapter.dispose()
+
+
+def test_type_change_no_false_positive_when_unchanged(tmp_path: Path):
+    repo_root = tmp_path / "db"
+    repo_root.mkdir()
+    _init_repo(repo_root)
+    (repo_root / "kunde.tbl").write_text(
+        "CREATE TABLE IF NOT EXISTS kunde (id INTEGER, code VARCHAR(10));", encoding="utf-8"
+    )
+    ref1 = _commit(repo_root, "v1")
+    db = tmp_path / "stable.db"
+    adapter = SqliteAdapter(ConnectionConfig(environment="sqlite", service=str(db)))
+    repo = Repo(repo_root)
+    plan1 = build_plan(repo, adapter, from_ref=None, to_ref=ref1,
+                       target="sqlite", dialect="sqlite")
+    adapter.apply([s.sql for s in plan1.steps])
+    adapter.record_deploy(ref1, [])
+    # re-plan the same schema against the live DB → no phantom modify step
+    plan2 = build_plan(repo, adapter, from_ref=None, to_ref=ref1,
+                       target="sqlite", dialect="sqlite")
+    assert not [s for s in plan2.steps if "modify column" in s.title]
+    adapter.dispose()
+
+
+def test_plan_against_worktree_sees_uncommitted_and_untracked(tmp_path: Path):
+    from dbly.repo import WORKTREE
+    repo_root = tmp_path / "db"
+    repo_root.mkdir()
+    _init_repo(repo_root)
+    (repo_root / "kunde.tbl").write_text(
+        "CREATE TABLE IF NOT EXISTS kunde (id INTEGER, name TEXT);", encoding="utf-8"
+    )
+    ref1 = _commit(repo_root, "v1")
+
+    db = tmp_path / "wt.db"
+    adapter = SqliteAdapter(ConnectionConfig(environment="sqlite", service=str(db)))
+    repo = Repo(repo_root)
+    adapter.apply([s.sql for s in build_plan(
+        repo, adapter, from_ref=None, to_ref=ref1, target="sqlite", dialect="sqlite").steps])
+    adapter.record_deploy(ref1, [])
+
+    # edit an existing file (uncommitted) + add a brand-new untracked object file
+    (repo_root / "kunde.tbl").write_text(
+        "CREATE TABLE IF NOT EXISTS kunde (id INTEGER, name TEXT, email TEXT);", encoding="utf-8"
+    )
+    (repo_root / "v_kunde.vw").write_text(
+        "CREATE VIEW v_kunde AS SELECT id FROM kunde;", encoding="utf-8"
+    )
+    plan = build_plan(repo, adapter, from_ref=ref1, to_ref=WORKTREE,
+                      target="sqlite", dialect="sqlite")
+    titles = " ".join(s.title for s in plan.steps)
+    assert "email" in titles                       # uncommitted column edit is planned
+    assert any(s.kind.value == "view" for s in plan.steps)  # untracked new object is planned
+    adapter.dispose()
+
+
+def test_repo_ref_names_decorates_tag_and_branch(tmp_path: Path):
+    repo_root = tmp_path / "db"
+    repo_root.mkdir()
+    _init_repo(repo_root)
+    (repo_root / "kunde.tbl").write_text("CREATE TABLE kunde (id INTEGER);", encoding="utf-8")
+    sha = _commit(repo_root, "v1")
+    _git(repo_root, "tag", "v0.1")
+    repo = Repo(repo_root)
+    names = repo.ref_names(sha)
+    assert "v0.1" in names
+    assert any(n in ("main", "master") for n in names)  # the current branch points here too

{dbly-0.2.0 → dbly-0.3.0}/tests/test_parsing.py

@@ -124,3 +124,39 @@ def test_plan_yaml_roundtrip():
     assert back.to_ref == "HEAD"
     assert back.steps[0].severity is Severity.ADDITIVE
     assert back.warnings == ["something"]
+
+
+def test_canonical_type_normalizes_numeric_scale_and_collation():
+    # omitted scale ≡ scale 0 (Oracle NUMBER(p) == NUMBER(p,0)); case/space-insensitive
+    assert parsing.canonical_type("NUMBER(10)") == parsing.canonical_type("number(10, 0)")
+    # a genuine precision change is preserved (bug: NUMBER → NUMBER(10) was missed)
+    assert parsing.types_differ("NUMBER", "NUMBER(10)")
+    assert parsing.types_differ("NUMBER(10)", "NUMBER(12)")
+    # SQL Server appends a COLLATE clause on reflected string types — not a real change
+    assert not parsing.types_differ("NVARCHAR(100)", 'NVARCHAR(100) COLLATE "SQL_Latin1_CI_AS"')
+    assert not parsing.types_differ("VARCHAR2(200)", "varchar2(200)")
+
+
+def test_render_plan_shows_step_note(capsys):
+    from rich.console import Console
+    plan = Plan(target="t", from_ref="abc", to_ref="HEAD")
+    plan.steps.append(
+        Step(
+            title="add NOT NULL column app.kunde.flag",
+            object_id=None,
+            kind=ObjectKind.TABLE,
+            severity=Severity.DESTRUCTIVE,
+            sql="ALTER TABLE app.kunde ADD flag NUMBER(1) NOT NULL;",
+            note="NOT NULL without default on existing table — unsafe",
+        )
+    )
+    report.render_plan(plan, Console(force_terminal=False, width=200))
+    out = capsys.readouterr().out
+    assert "NOT NULL without default" in out  # the hint is surfaced, not just stored
+
+
+def test_decorate_ref_git_style():
+    assert report._decorate_ref(None, None) == "∅"
+    assert report._decorate_ref("WORKTREE", None) == "working tree"
+    assert report._decorate_ref("9ff5e440abc", {"9ff5e440abc": "v0.1, main"}) == "v0.1, main (9ff5e440)"
+    assert report._decorate_ref("deadbeef", None) == "deadbeef"  # no names → raw sha