dbly 0.0.1__py3-none-any.whl

dbly/cli.py

@@ -0,0 +1,245 @@
+"""dbly command-line interface (CONCEPT.md §14).
+
+    dbly plan      --to <ref> [--from <ref>] --target <profile>
+    dbly apply     [<plan.yaml>] [--to <ref>] --target <profile> [--allow-destructive]
+    dbly bootstrap --to <ref> --target <profile>
+    dbly check     --target <profile> [--to <ref>]
+    dbly status    --target <profile>
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from dbly import __version__, hooks, initializer, report
+from dbly.adapters import get_adapter
+from dbly.config import resolve_target
+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
+
+app = typer.Typer(
+    name="dbly",
+    help="State-based, cross-engine database deployment — git-driven, parser-assisted.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+console = Console()
+err = Console(stderr=True)
+
+
+def _version(value: bool) -> None:
+    if value:
+        console.print(f"dbly {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _main(
+    version: bool = typer.Option(  # noqa: ARG001
+        False, "--version", callback=_version, is_eager=True, help="Show version and exit."
+    ),
+) -> None:
+    pass
+
+
+def _make_plan(repo_path: Path, target: str, from_ref: Optional[str], to_ref: str) -> 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)
+        if from_ref is not None:
+            resolved_from = repo.resolve_ref(from_ref)
+        else:
+            resolved_from = adapter.get_deployed_ref()  # already a SHA, or None (bootstrap)
+        return build_plan(
+            repo, adapter,
+            from_ref=resolved_from, to_ref=resolved_to,
+            target=target, dialect=dialect,
+        )
+    finally:
+        adapter.dispose()
+
+
+@app.command()
+def plan(
+    to: str = typer.Option("HEAD", "--to", help="git ref to deploy (release tag/branch)."),
+    from_ref: Optional[str] = typer.Option(
+        None, "--from", help="baseline ref (default: deployed ref from dbly_state)."
+    ),
+    target: str = typer.Option(..., "--target", help="connection profile or env name."),
+    repo_path: Path = typer.Option(Path("."), "--repo", help="repository root."),
+    out: Optional[Path] = typer.Option(None, "--out", help="write the plan as YAML."),
+    sql: Optional[Path] = typer.Option(
+        None, "--sql", help="write an executable SQL script for a hand/offline deploy."
+    ),
+) -> None:
+    """Compute and show the deployment plan."""
+    plan_obj = _make_plan(repo_path, target, from_ref, to)
+    report.render_plan(plan_obj, console)
+    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]")
+    if sql:
+        # state_table_ddl / record_deploy_sql are pure string builders — no DB connection.
+        adapter = get_adapter(resolve_target(target))
+        try:
+            script = report.plan_to_sql(
+                plan_obj,
+                state_ddl=adapter.state_table_ddl(),
+                record_sql=adapter.record_deploy_sql(plan_obj.to_ref),
+            )
+        finally:
+            adapter.dispose()
+        sql.write_text(script, encoding="utf-8")
+        console.print(f"[dim]deploy SQL written to {sql}[/dim]")
+
+
+@app.command()
+def apply(
+    plan_file: Optional[Path] = typer.Argument(None, help="a YAML plan from `dbly plan`."),
+    to: str = typer.Option("HEAD", "--to"),
+    from_ref: Optional[str] = typer.Option(None, "--from"),
+    target: str = typer.Option(..., "--target"),
+    repo_path: Path = typer.Option(Path("."), "--repo"),
+    allow_destructive: bool = typer.Option(
+        False, "--allow-destructive", help="execute destructive steps too."
+    ),
+    py_interpreter: str = typer.Option(
+        "python", "--py-interpreter", help="interpreter for .py hooks (e.g. ArcGIS propy)."
+    ),
+) -> None:
+    """Apply a plan to the target database (re-computes one unless a file is given)."""
+    if plan_file is not None:
+        plan_obj = report.plan_from_yaml(plan_file.read_text(encoding="utf-8"))
+        target = plan_obj.target
+    else:
+        plan_obj = _make_plan(repo_path, target, from_ref, to)
+
+    report.render_plan(plan_obj, console)
+
+    destructive = [s for s in plan_obj.steps if s.severity is Severity.DESTRUCTIVE]
+    if destructive and not allow_destructive:
+        err.print(
+            "[red]aborting:[/red] plan has destructive steps; pass --allow-destructive "
+            "to proceed."
+        )
+        raise typer.Exit(code=1)
+
+    statements = [
+        s.sql for s in plan_obj.steps
+        if allow_destructive or s.severity is not Severity.DESTRUCTIVE
+    ]
+    if not statements:
+        console.print("[green]nothing to apply.[/green]")
+        return
+
+    repo = Repo(repo_path)
+    cfg = resolve_target(target)
+    adapter = get_adapter(cfg)
+    try:
+        _run_hooks(repo, "pre", py_interpreter)
+        adapter.ensure_state_table()
+        adapter.apply(statements)
+        adapter.record_deploy(plan_obj.to_ref, migration_ids=[])
+        _run_hooks(repo, "post", py_interpreter)
+    finally:
+        adapter.dispose()
+    console.print(f"[green]applied[/green] {len(statements)} step(s); "
+                  f"deployed ref → {plan_obj.to_ref}")
+
+
+@app.command()
+def init(
+    init_target: str = typer.Option(
+        ..., "--init-target",
+        help="privileged connection profile (superuser / maintenance DB).",
+    ),
+    repo_path: Path = typer.Option(Path("."), "--repo"),
+    init_dir: str = typer.Option("init", "--dir", help="folder of ordered init SQL scripts."),
+) -> None:
+    """Run privileged greenfield groundwork (CREATE DATABASE/ROLE/EXTENSION).
+
+    Greenfield only — brownfield (a handed-over database) skips this entirely.
+    """
+    repo = Repo(repo_path)
+    scripts = initializer.discover_init_scripts(repo.root, init_dir)
+    if not scripts:
+        console.print(f"[yellow]no init scripts in {init_dir}/ — nothing to do.[/yellow]")
+        return
+    adapter = get_adapter(resolve_target(init_target))
+    try:
+        for s in scripts:
+            adapter.run_init_script(s.read_text(encoding="utf-8"))
+            console.print(f"[green]ran[/green] {init_dir}/{s.name}")
+    finally:
+        adapter.dispose()
+    console.print(f"[green]init complete[/green] — {len(scripts)} script(s).")
+
+
+@app.command()
+def bootstrap(
+    to: str = typer.Option("HEAD", "--to"),
+    target: str = typer.Option(..., "--target"),
+    repo_path: Path = typer.Option(Path("."), "--repo"),
+) -> 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)
+    console.print("\n[dim]review, then run `dbly apply` to execute.[/dim]")
+
+
+@app.command()
+def status(target: str = typer.Option(..., "--target")) -> None:
+    """Show the deployed ref recorded on the target."""
+    cfg = resolve_target(target)
+    adapter = get_adapter(cfg)
+    try:
+        ref = adapter.get_deployed_ref()
+    finally:
+        adapter.dispose()
+    if ref:
+        console.print(f"deployed ref: [cyan]{ref}[/cyan]")
+    else:
+        console.print("[yellow]no deploy recorded — database is unmanaged or empty.[/yellow]")
+
+
+@app.command()
+def check(
+    target: str = typer.Option(..., "--target"),
+    to: str = typer.Option("HEAD", "--to"),
+    repo_path: Path = typer.Option(Path("."), "--repo"),
+) -> None:
+    """Detect drift: compare desired state at <to> against the live database."""
+    plan_obj = _make_plan(repo_path, target, None, to)
+    drift = [s for s in plan_obj.steps] + plan_obj.warnings
+    if not drift:
+        console.print("[green]no drift — database matches desired state.[/green]")
+        return
+    report.render_plan(plan_obj, console)
+    console.print("\n[yellow]drift detected (see steps/warnings above).[/yellow]")
+
+
+def _run_hooks(repo: Repo, phase: str, py_interpreter: str) -> None:
+    for hook in hooks.discover_hooks(repo.root, phase):
+        if hook.suffix.lower() == ".py":
+            res = hooks.run_py_hook(hook, interpreter=py_interpreter)
+            if not res.ok:
+                raise hooks.HookError(res)
+            console.print(f"[dim]hook ok: {hook.name}[/dim]")
+        # NOTE: .sql hooks are applied via the adapter in a later iteration.
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

dbly/config.py

@@ -0,0 +1,101 @@
+"""Connection profiles — reuses dbression's DBFit-compatible ``connection.properties``.
+
+Format (same as dbression, so existing profiles work unchanged):
+
+    # 1) full connection string
+    connection-string=postgresql://user:pw@host:5432/db
+
+    # 2) OR separate parts
+    service=host:5432
+    username=app
+    password=${DB_PASSWORD}      # ${ENV} placeholders expand from os.environ
+    database=appdb
+
+dbly adds one key:
+
+    environment=postgres         # postgres | oracle | sqlserver | sqlite
+
+``${VAR}`` placeholders make profiles CI/CD-safe — keep credentials in pipeline secrets
+(e.g. Bitbucket), never in the repo. A profile may also be supplied entirely via env:
+``DBLY_TARGET`` (a path) or inline ``DBLY_CONNECTION_STRING`` + ``DBLY_ENVIRONMENT``.
+"""
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_VAR_RE = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+def _expand_vars(value: str) -> str:
+    def repl(m: re.Match[str]) -> str:
+        name = m.group(1)
+        try:
+            return os.environ[name]
+        except KeyError as exc:
+            raise KeyError(
+                f"connection profile references undefined environment variable: ${{{name}}}"
+            ) from exc
+
+    return _VAR_RE.sub(repl, value)
+
+
+@dataclass(slots=True)
+class ConnectionConfig:
+    environment: str | None = None
+    connection_string: str | None = None
+    service: str | None = None
+    username: str | None = None
+    password: str | None = None
+    extra: dict[str, str] = field(default_factory=dict)
+
+
+def load_profile(path: Path) -> ConnectionConfig:
+    """Parse a Java-style ``.properties`` connection profile."""
+    cfg = ConnectionConfig()
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or line.startswith("!"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip().lower()
+        value = _expand_vars(value.strip())
+        if key == "connection-string":
+            cfg.connection_string = value
+        elif key in ("environment", "databaseenvironment", "engine"):
+            cfg.environment = value
+        elif key == "service":
+            cfg.service = value
+        elif key == "username":
+            cfg.username = value
+        elif key == "password":
+            cfg.password = value
+        else:
+            cfg.extra[key] = value
+    return cfg
+
+
+def resolve_target(target: str | None) -> ConnectionConfig:
+    """Resolve a ``--target`` into a ConnectionConfig.
+
+    Order: explicit file path → ``DBLY_TARGET`` (file) → inline env vars.
+    """
+    if target:
+        return load_profile(Path(target))
+    env_path = os.environ.get("DBLY_TARGET")
+    if env_path:
+        return load_profile(Path(env_path))
+    cs = os.environ.get("DBLY_CONNECTION_STRING")
+    if cs:
+        return ConnectionConfig(
+            environment=os.environ.get("DBLY_ENVIRONMENT"),
+            connection_string=cs,
+        )
+    raise ValueError(
+        "no target given — pass --target <profile> or set DBLY_TARGET / "
+        "DBLY_CONNECTION_STRING (+ DBLY_ENVIRONMENT)"
+    )

dbly/engine.py

@@ -0,0 +1,138 @@
+"""Build SQLAlchemy engines from connection profiles + detect the dialect.
+
+Mirrors dbression's engine builder (same URL conventions) so profiles are interchangeable.
+The ``environment`` key (postgres | oracle | sqlserver | sqlite) selects the driver; for a
+full ``connection-string`` we sniff the scheme when ``environment`` is absent.
+"""
+from __future__ import annotations
+
+import os
+import threading
+
+from sqlalchemy import URL, Engine, create_engine
+
+from dbly.config import ConnectionConfig
+
+_POSTGRES = {"postgres", "postgresql", "pg"}
+_ORACLE = {"oracle"}
+_MSSQL = {"sqlserver", "mssql", "ms-sql"}
+_SQLITE = {"sqlite", "sqlite3"}
+
+_THICK_LOCK = threading.Lock()
+_THICK_DONE = False
+
+
+def detect_dialect(cfg: ConnectionConfig) -> str:
+    if cfg.environment:
+        return cfg.environment.strip().lower()
+    cs = (cfg.connection_string or "").lower()
+    if cs.startswith(("postgres", "jdbc:postgresql")):
+        return "postgres"
+    if cs.startswith(("oracle", "jdbc:oracle")):
+        return "oracle"
+    if cs.startswith(("mssql", "sqlserver", "jdbc:sqlserver")):
+        return "sqlserver"
+    if cs.startswith("sqlite"):
+        return "sqlite"
+    raise ValueError(
+        "cannot determine database environment — set `environment=` in the profile"
+    )
+
+
+def make_engine(cfg: ConnectionConfig) -> Engine:
+    """Build a SQLAlchemy engine. No autocommit — adapters manage transactions."""
+    env = detect_dialect(cfg)
+    if env in _POSTGRES:
+        url = _postgres_url(cfg)
+    elif env in _ORACLE:
+        _maybe_init_oracle_thick()
+        url = _oracle_url(cfg)
+    elif env in _MSSQL:
+        url = _mssql_url(cfg)
+    elif env in _SQLITE:
+        url = _sqlite_url(cfg)
+    else:
+        raise ValueError(f"unknown environment: {env!r}")
+    return create_engine(url, pool_pre_ping=True)
+
+
+def _maybe_init_oracle_thick() -> None:
+    global _THICK_DONE
+    if _THICK_DONE:
+        return
+    lib_dir = os.environ.get("DBLY_ORACLE_CLIENT_LIB_DIR")
+    if not lib_dir:
+        return
+    with _THICK_LOCK:
+        if _THICK_DONE:
+            return
+        import oracledb  # noqa: PLC0415
+
+        oracledb.init_oracle_client(lib_dir=lib_dir)
+        _THICK_DONE = True
+
+
+def _postgres_url(cfg: ConnectionConfig) -> URL | str:
+    if cfg.connection_string:
+        cs = cfg.connection_string
+        if cs.startswith("jdbc:postgresql://"):
+            return f"postgresql+psycopg://{cs[len('jdbc:postgresql://'):]}"
+        if cs.startswith(("postgresql://", "postgres://")):
+            _, _, rest = cs.partition("://")
+            return f"postgresql+psycopg://{rest}"
+        return cs
+    host, port = _split_host_port(cfg.service)
+    return URL.create(
+        "postgresql+psycopg",
+        username=cfg.username,
+        password=cfg.password,
+        host=host,
+        port=port,
+        database=cfg.extra.get("database"),
+    )
+
+
+def _oracle_url(cfg: ConnectionConfig) -> URL | str:
+    if cfg.connection_string:
+        cs = cfg.connection_string.replace("jdbc:oracle:thin:@", "")
+        return f"oracle+oracledb://{cfg.username or ''}:{cfg.password or ''}@{cs}"
+    return URL.create(
+        "oracle+oracledb",
+        username=cfg.username,
+        password=cfg.password,
+        query={"dsn": cfg.service or ""},
+    )
+
+
+def _mssql_url(cfg: ConnectionConfig) -> URL | str:
+    if cfg.connection_string:
+        return cfg.connection_string
+    host, port = _split_host_port(cfg.service)
+    return URL.create(
+        "mssql+pymssql",
+        username=cfg.username,
+        password=cfg.password,
+        host=host,
+        port=port,
+        database=cfg.extra.get("database"),
+    )
+
+
+def _sqlite_url(cfg: ConnectionConfig) -> URL | str:
+    if cfg.connection_string:
+        return cfg.connection_string
+    path = cfg.service or cfg.extra.get("database") or ":memory:"
+    return f"sqlite:///{path}"
+
+
+def _split_host_port(service: str | None) -> tuple[str | None, int | None]:
+    if not service:
+        return None, None
+    if ":" in service:
+        host, _, port_str = service.partition(":")
+        port_str = port_str.split("/", 1)[0]
+        try:
+            return host, int(port_str)
+        except ValueError:
+            return service, None
+    return service, None

dbly/hooks.py

@@ -0,0 +1,62 @@
+"""Global pre-/post-deploy hooks (CONCEPT.md §11).
+
+Hooks accept ``.sql`` and ``.py`` files. ``.py`` hooks run as an isolated subprocess under
+a **configurable interpreter** — crucial for ArcPy, which lives in ArcGIS's bundled Python,
+not in dbly's uv environment. Robust error handling: timeout, full stdout/stderr capture,
+explicit failure semantics.
+
+Layout convention (best practice, not enforced)::
+
+    hooks/pre/*.sql|*.py
+    hooks/post/*.sql|*.py
+"""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(slots=True)
+class HookResult:
+    hook: Path
+    ok: bool
+    stdout: str
+    stderr: str
+    returncode: int | None
+
+
+class HookError(RuntimeError):
+    def __init__(self, result: HookResult):
+        self.result = result
+        super().__init__(
+            f"hook failed: {result.hook} (rc={result.returncode})\n{result.stderr}"
+        )
+
+
+def discover_hooks(repo_root: Path, phase: str) -> list[Path]:
+    d = repo_root / "hooks" / phase
+    if not d.is_dir():
+        return []
+    return sorted(p for p in d.iterdir() if p.suffix.lower() in (".sql", ".py"))
+
+
+def run_py_hook(
+    hook: Path,
+    *,
+    interpreter: str,
+    timeout: float | None = None,
+    env: dict[str, str] | None = None,
+) -> HookResult:
+    """Run a ``.py`` hook under an external interpreter (e.g. ArcGIS ``propy``)."""
+    try:
+        proc = subprocess.run(
+            [interpreter, str(hook)],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=env,
+        )
+    except subprocess.TimeoutExpired as exc:
+        return HookResult(hook, False, exc.stdout or "", "timeout exceeded", None)
+    return HookResult(hook, proc.returncode == 0, proc.stdout, proc.stderr, proc.returncode)

dbly/initializer.py

@@ -0,0 +1,19 @@
+"""Privileged greenfield groundwork (CONCEPT.md §6).
+
+Init scripts live in ``init/`` (ordered by filename) and are run **verbatim** — they are
+imperative groundwork (``CREATE DATABASE`` / roles / extensions / base schemas), not
+declarative objects, so they are neither parsed nor classified. Run under a separate
+privileged profile (``--init-target``), explicitly via ``dbly init``, never as part of
+``apply``. Greenfield runs this once; brownfield skips it entirely.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def discover_init_scripts(repo_root: Path, dirname: str = "init") -> list[Path]:
+    """Ordered ``.sql`` init scripts (lexicographic, so prefix ``01_``, ``02_`` …)."""
+    d = repo_root / dirname
+    if not d.is_dir():
+        return []
+    return sorted(p for p in d.iterdir() if p.is_file() and p.suffix.lower() == ".sql")

dbly/model.py

@@ -0,0 +1,119 @@
+"""Core data model shared across parsing, planning and applying.
+
+Two object classes drive everything (CONCEPT.md §3):
+
+* **REPLACEABLE** (Klasse 1) — views, functions, procedures, packages, triggers, types,
+  grants. Deployed by re-applying the object wholesale (``CREATE OR REPLACE`` /
+  drop-and-create). Idempotent, no ledger needed.
+* **STATEFUL** (Klasse 2) — tables. Never blindly re-applied; the desired ``CREATE TABLE``
+  is diffed against the live schema and an additive ``ALTER`` is generated. Destructive
+  deltas are flagged, never auto-applied.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+
+class ObjectClass(str, Enum):
+    REPLACEABLE = "replaceable"  # Klasse 1
+    STATEFUL = "stateful"        # Klasse 2 (tables)
+
+
+class ObjectKind(str, Enum):
+    TABLE = "table"
+    VIEW = "view"
+    FUNCTION = "function"
+    PROCEDURE = "procedure"
+    PACKAGE = "package"
+    TRIGGER = "trigger"
+    TYPE = "type"
+    GRANT = "grant"
+    UNKNOWN = "unknown"
+
+    @property
+    def object_class(self) -> ObjectClass:
+        return ObjectClass.STATEFUL if self is ObjectKind.TABLE else ObjectClass.REPLACEABLE
+
+
+@dataclass(slots=True)
+class Column:
+    """A table column — used both for the desired state (parsed from ``CREATE TABLE``)
+    and the actual state (introspected from the live database)."""
+
+    name: str
+    type: str
+    nullable: bool = True
+    default: str | None = None
+
+    def key(self) -> str:
+        return self.name.lower()
+
+
+@dataclass(slots=True)
+class ObjectId:
+    """Schema-qualified identity of a database object."""
+
+    schema: str | None
+    name: str
+
+    def __str__(self) -> str:
+        return f"{self.schema}.{self.name}" if self.schema else self.name
+
+    def key(self) -> str:
+        return str(self).lower()
+
+
+@dataclass(slots=True)
+class ParsedObject:
+    """A single database object discovered by parsing a source file."""
+
+    id: ObjectId
+    kind: ObjectKind
+    sql: str
+    source_file: Path
+    depends_on: set[str] = field(default_factory=set)  # ObjectId.key() of referenced objects
+
+    @property
+    def object_class(self) -> ObjectClass:
+        return self.kind.object_class
+
+
+class ChangeType(str, Enum):
+    ADDED = "added"
+    MODIFIED = "modified"
+    DELETED = "deleted"
+
+
+class Severity(str, Enum):
+    ADDITIVE = "additive"        # safe to auto-apply
+    DESTRUCTIVE = "destructive"  # requires --allow-destructive or an explicit ALTER
+
+
+@dataclass(slots=True)
+class Step:
+    """One ordered unit of work in a plan."""
+
+    title: str
+    object_id: ObjectId | None
+    kind: ObjectKind
+    severity: Severity
+    sql: str
+    source_file: Path | None = None
+    note: str | None = None
+
+
+@dataclass(slots=True)
+class Plan:
+    """An ordered, reviewable set of steps — the artifact of ``dbly plan``."""
+
+    target: str
+    from_ref: str | None
+    to_ref: str
+    steps: list[Step] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def has_destructive(self) -> bool:
+        return any(s.severity is Severity.DESTRUCTIVE for s in self.steps)