db-git 0.1.0__py3-none-any.whl

git_db/backends/postgresql/template.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import psycopg
+from psycopg import sql
+
+from git_db.backends import DatabaseBackend, DbConnection
+from git_db.backends.postgresql.connections import handle_active_connections
+from git_db.db import parse_database_url
+from git_db.errors import DatabaseError, SnapshotError, TerminationTimeout
+from git_db.storage import (
+    make_metadata,
+    metadata_path,
+    snapshot_db_name,
+    write_metadata,
+)
+
+if TYPE_CHECKING:
+    from git_db.config import GitDbConfig
+
+
+class TemplateStrategy:
+    """
+    Snapshot strategy using PostgreSQL template databases.
+    """
+
+    name = "template"
+
+    def __init__(self, backend: DatabaseBackend) -> None:
+        self._backend = backend
+
+    def save(
+        self,
+        db_url: str,
+        branch: str,
+        snapshot_dir: Path,
+        config: GitDbConfig,
+    ) -> None:
+        params = self._backend.apply_url_defaults(parse_database_url(db_url))
+        dbname = str(params["dbname"])
+        snapshot_name = snapshot_db_name(
+            branch,
+            dbname,
+            self._backend.max_identifier_length,
+        )
+
+        conn = self._backend.connect_maintenance(params)
+        try:
+            handle_active_connections(conn, dbname, config)
+            handle_active_connections(conn, snapshot_name, config)
+
+            conn.execute(
+                sql.SQL("DROP DATABASE IF EXISTS {} WITH (FORCE)").format(
+                    sql.Identifier(snapshot_name)
+                )
+            )
+
+            _create_from_template(conn, snapshot_name, dbname)
+        except (psycopg.Error, DatabaseError) as e:
+            raise SnapshotError(f"Template save failed: {e}") from e
+        finally:
+            conn.close()
+
+        write_metadata(
+            snapshot_dir,
+            make_metadata(
+                branch=branch,
+                database=dbname,
+                strategy=self.name,
+                engine=self._backend.engine,
+                engine_version="",
+                file_size_bytes=None,
+            ),
+        )
+
+    def restore(
+        self,
+        db_url: str,
+        branch: str,
+        snapshot_dir: Path,
+        config: GitDbConfig,
+    ) -> None:
+        params = self._backend.apply_url_defaults(parse_database_url(db_url))
+        dbname = str(params["dbname"])
+        snapshot_name = snapshot_db_name(
+            branch,
+            dbname,
+            self._backend.max_identifier_length,
+        )
+
+        conn = self._backend.connect_maintenance(params)
+        try:
+            handle_active_connections(conn, dbname, config)
+
+            conn.execute(
+                sql.SQL("DROP DATABASE IF EXISTS {} WITH (FORCE)").format(
+                    sql.Identifier(dbname)
+                )
+            )
+
+            _create_from_template(conn, dbname, snapshot_name)
+        except (psycopg.Error, DatabaseError, TerminationTimeout) as e:
+            raise SnapshotError(f"Template restore failed: {e}") from e
+        finally:
+            conn.close()
+
+    def cleanup(
+        self,
+        branch: str,
+        snapshot_dir: Path,
+        config: GitDbConfig,
+    ) -> None:
+        """
+        Drop the snapshot database and remove the metadata file.
+        """
+        params = self._backend.apply_url_defaults(
+            parse_database_url(config.database_url)
+        )
+        dbname = str(params["dbname"])
+        snapshot_name = snapshot_db_name(
+            branch,
+            dbname,
+            self._backend.max_identifier_length,
+        )
+
+        try:
+            conn = self._backend.connect_maintenance(params)
+            try:
+                handle_active_connections(conn, snapshot_name, config)
+                conn.execute(
+                    sql.SQL("DROP DATABASE IF EXISTS {} WITH (FORCE)").format(
+                        sql.Identifier(snapshot_name)
+                    )
+                )
+            finally:
+                conn.close()
+        except DatabaseError:
+            pass
+
+        meta = metadata_path(snapshot_dir, branch)
+        if meta.exists():
+            meta.unlink()
+
+
+def _create_from_template(
+    conn: DbConnection,
+    target: str,
+    template: str,
+) -> None:
+    """
+    Issue CREATE DATABASE using PostgreSQL's default copy strategy.
+    """
+    conn.execute(
+        sql.SQL("CREATE DATABASE {} TEMPLATE {}").format(
+            sql.Identifier(target),
+            sql.Identifier(template),
+        )
+    )

git_db/cli/__init__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from git_db.backends import get_backend
+
+from . import branch, hook, init, inspect, snapshot  # noqa: F401
+from ._console import app, hook_app
+
+__all__ = ["app", "get_backend", "hook_app"]

git_db/cli/_common.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import typer
+
+from git_db.config import find_project_root
+from git_db.git import get_git_dir
+
+from ._console import console
+
+
+def check_enabled() -> str:
+    """
+    Return a Rich-formatted string showing enabled/disabled status.
+    """
+    git_dir = get_git_dir()
+    if git_dir and (git_dir / "git-db" / "disabled").exists():
+        return "[yellow]no[/] (run [cyan]git-db enable[/] to re-enable)"
+    return "[green]yes[/]"
+
+
+def require_init() -> Path:
+    """
+    Ensure git-db has been initialized. Returns project root.
+    """
+    root = find_project_root()
+    if root is None or not (root / ".git-db.toml").exists():
+        console.print(
+            "[red]Error:[/] git-db is not initialized. Run [cyan]git-db init[/] first."
+        )
+        raise typer.Exit(1)
+    return root
+
+
+def debug_enabled() -> bool:
+    """
+    Whether GIT_DB_DEBUG is set to a truthy value.
+    """
+    return os.environ.get("GIT_DB_DEBUG", "").lower() in ("1", "true", "yes")

git_db/cli/_console.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+app = typer.Typer(
+    name="git-db",
+    help=(
+        "Keep your database in sync with your git branches. "
+        "Currently supports PostgreSQL."
+    ),
+    rich_markup_mode="rich",
+)
+
+hook_app = typer.Typer(name="hook", help="Manage the post-checkout git hook.")
+app.add_typer(hook_app)
+
+console = Console(stderr=True)

git_db/cli/_format.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from urllib.parse import urlparse, urlunparse
+
+
+def format_age(iso_timestamp: str) -> str:
+    """
+    Return human-readable age like '2h ago', '3d ago'.
+    """
+    try:
+        created = datetime.fromisoformat(iso_timestamp)
+        now = datetime.now(UTC)
+        delta = now - created
+        seconds = int(delta.total_seconds())
+
+        if seconds < 60:
+            return "just now"
+        if seconds < 3600:
+            return f"{seconds // 60}m ago"
+        if seconds < 86400:
+            return f"{seconds // 3600}h ago"
+        if seconds < 604800:
+            return f"{seconds // 86400}d ago"
+        return f"{seconds // 604800}w ago"
+    except (ValueError, TypeError):
+        return "unknown"
+
+
+def format_size(size_bytes: int | None) -> str:
+    """
+    Return human-readable size like '1.2 MB', '340 KB'.
+    """
+    if size_bytes is None:
+        return "template"
+    if size_bytes < 1024:
+        return f"{size_bytes} B"
+    if size_bytes < 1024 * 1024:
+        return f"{size_bytes / 1024:.1f} KB"
+    if size_bytes < 1024 * 1024 * 1024:
+        return f"{size_bytes / (1024 * 1024):.1f} MB"
+    return f"{size_bytes / (1024 * 1024 * 1024):.1f} GB"
+
+
+def mask_url(url: str) -> str:
+    """
+    Replace password in database URL with ****.
+    """
+    parsed = urlparse(url)
+    if parsed.password:
+        netloc = f"{parsed.username}:****@{parsed.hostname}"
+        if parsed.port:
+            netloc += f":{parsed.port}"
+        masked = parsed._replace(netloc=netloc)
+        return urlunparse(masked)
+    return url

git_db/cli/_prompts.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+
+import typer
+
+from git_db.git import get_current_branch
+
+from ._console import console
+
+
+def resolve_with_prompt(
+    flag_value: str | None,
+    existing: object | None,
+    prompt_text: str,
+    required: bool = False,
+) -> str:
+    """
+    Resolve a string value from flag, existing config, or prompt.
+    """
+    if flag_value is not None:
+        return flag_value
+    if existing:
+        return str(existing)
+    if required and sys.stdin.isatty():
+        return typer.prompt(prompt_text)
+    return ""
+
+
+def resolve_choice(
+    flag_value: str | None,
+    existing: object | None,
+    prompt_text: str,
+    choices: dict[str, str],
+    labels: dict[str, str],
+    default: str,
+) -> str:
+    """
+    Resolve a choice from flag, existing config, or interactive prompt.
+    """
+    if flag_value is not None:
+        if flag_value in choices.values():
+            return flag_value
+        console.print(f"[red]Error:[/] Invalid value '{flag_value}'.")
+        raise typer.Exit(1)
+
+    reverse = {v: k for k, v in choices.items()}
+    existing_key = reverse.get(str(existing)) if existing else None
+    default_key = existing_key or default
+    default_value = choices[default_key]
+
+    if not sys.stdin.isatty():
+        return (
+            str(existing)
+            if existing and str(existing) in choices.values()
+            else default_value
+        )
+
+    console.print(f"  {prompt_text}:\n")
+    for key, label in labels.items():
+        marker = " (current)" if key == existing_key else ""
+        console.print(f"    {key}. {label}{marker}")
+
+    console.print()
+    result = typer.prompt("  Choice", default=default_key)
+    result = str(result).strip()
+    console.print()
+
+    if result in choices:
+        return choices[result]
+    if result in choices.values():
+        return result
+    return default_value
+
+
+def confirm_prune(
+    header: str,
+    items: list[tuple[str, str | None]],
+    yes: bool,
+) -> bool:
+    """
+    Display items to be pruned and ask for confirmation.
+    """
+    console.print(header)
+    for name, subtitle in items:
+        if subtitle:
+            console.print(f"  {name}  [dim]({subtitle})[/]")
+        else:
+            console.print(f"  {name}")
+    console.print()
+
+    if yes:
+        return True
+
+    if not sys.stdin.isatty():
+        console.print(
+            "[red]Error:[/] Refusing to prune in non-interactive mode. "
+            "Pass [cyan]--yes[/] to proceed, or [cyan]--dry-run[/] to preview."
+        )
+        raise typer.Exit(1)
+
+    return typer.confirm("This is irreversible. Continue?", default=False)
+
+
+def detect_default_branch() -> str:
+    """
+    Detect the default branch name from git.
+    """
+    result = subprocess.run(
+        ["git", "symbolic-ref", "refs/remotes/origin/HEAD"],
+        capture_output=True,
+        text=True,
+        timeout=10,
+    )
+    if result.returncode == 0:
+        ref = result.stdout.strip()
+        return ref.split("/")[-1]
+
+    current = get_current_branch()
+    return current or "main"

git_db/cli/branch.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from git_db.backends import get_backend
+from git_db.config import load_config
+from git_db.db import parse_database_url
+from git_db.errors import GitDbError
+from git_db.git import get_current_branch, get_git_dir
+from git_db.storage import branch_db_name
+
+from ._common import debug_enabled, require_init
+from ._console import app, console
+
+
+@app.command()
+def create(
+    branch: Annotated[str | None, typer.Argument()] = None,
+    database_url: Annotated[
+        str | None, typer.Option("--database-url", envvar="DATABASE_URL")
+    ] = None,
+) -> None:
+    """
+    Proactively create a per-branch database before checkout.
+
+    Per-branch mode only.
+    """
+    require_init()
+    try:
+        config = load_config(cli_overrides={"database_url": database_url})
+
+        if config.mode != "per-branch":
+            console.print(
+                "Shared mode: use [cyan]git-db save[/] to snapshot the database."
+            )
+            return
+
+        git_dir = get_git_dir()
+        if git_dir is None:
+            console.print("[red]Error:[/] Not inside a git repository.")
+            raise typer.Exit(1)
+
+        if branch is None:
+            branch = get_current_branch()
+            if branch is None:
+                console.print("[red]Error:[/] HEAD is detached. Specify a branch name.")
+                raise typer.Exit(1)
+
+        backend = get_backend(config.database_url)
+        params = backend.apply_url_defaults(parse_database_url(config.database_url))
+        dbname = str(params["dbname"])
+        manager = backend.branch_db_manager(config)
+        target_db = branch_db_name(
+            branch,
+            dbname,
+            config.default_branch,
+            backend.max_identifier_length,
+        )
+
+        if manager.exists(target_db):
+            console.print(
+                f"[yellow]Branch database '{target_db}' already exists.[/] "
+                "Use [cyan]git-db reset[/] to recreate from seed."
+            )
+            raise typer.Exit(1)
+
+        source_db = dbname
+        created_from = config.default_branch
+
+        current = get_current_branch()
+        if current:
+            candidate = branch_db_name(
+                current,
+                dbname,
+                config.default_branch,
+                backend.max_identifier_length,
+            )
+            if manager.exists(candidate):
+                source_db = candidate
+                created_from = current
+
+        manager.create(target_db, source_db, branch, created_from, git_dir)
+        console.print(f"[green]Created[/] database: {target_db}")
+    except GitDbError as e:
+        console.print(f"[red]Error:[/] {e}")
+        raise typer.Exit(1) from e
+    except typer.Exit:
+        raise
+    except Exception as e:
+        if debug_enabled():
+            raise
+        console.print(
+            f"[red]Error:[/] Unexpected error: {e}\n"
+            "[dim]Set GIT_DB_DEBUG=1 to see the full traceback.[/]"
+        )
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def reset(
+    branch: Annotated[str | None, typer.Argument()] = None,
+    database_url: Annotated[
+        str | None, typer.Option("--database-url", envvar="DATABASE_URL")
+    ] = None,
+) -> None:
+    """
+    Drop and recreate a branch database from seed (per-branch mode only).
+    """
+    require_init()
+    try:
+        config = load_config(cli_overrides={"database_url": database_url})
+
+        if config.mode != "per-branch":
+            console.print(
+                "Shared mode: use [cyan]git-db restore[/] to restore a snapshot."
+            )
+            return
+
+        git_dir = get_git_dir()
+        if git_dir is None:
+            console.print("[red]Error:[/] Not inside a git repository.")
+            raise typer.Exit(1)
+
+        if branch is None:
+            branch = get_current_branch()
+            if branch is None:
+                console.print("[red]Error:[/] HEAD is detached. Specify a branch name.")
+                raise typer.Exit(1)
+
+        backend = get_backend(config.database_url)
+        params = backend.apply_url_defaults(parse_database_url(config.database_url))
+        dbname = str(params["dbname"])
+        manager = backend.branch_db_manager(config)
+        target_db = branch_db_name(
+            branch,
+            dbname,
+            config.default_branch,
+            backend.max_identifier_length,
+        )
+        seed_db = dbname
+
+        if branch == config.default_branch:
+            console.print(
+                "[yellow]Cannot reset the default branch database.[/] "
+                "It is the seed for all other branches."
+            )
+            raise typer.Exit(1)
+
+        if manager.exists(target_db):
+            manager.drop(target_db, branch, git_dir)
+
+        manager.create(target_db, seed_db, branch, config.default_branch, git_dir)
+        console.print(f"[green]Reset[/] database '{target_db}' from seed '{seed_db}'")
+    except GitDbError as e:
+        console.print(f"[red]Error:[/] {e}")
+        raise typer.Exit(1) from e
+    except typer.Exit:
+        raise
+    except Exception as e:
+        if debug_enabled():
+            raise
+        console.print(
+            f"[red]Error:[/] Unexpected error: {e}\n"
+            "[dim]Set GIT_DB_DEBUG=1 to see the full traceback.[/]"
+        )
+        raise typer.Exit(1) from e

git_db/cli/hook.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import typer
+
+from git_db.config import load_config
+from git_db.errors import GitDbError
+from git_db.git import get_git_dir, handle_post_checkout, install_hook, remove_hook
+
+from ._console import app, console, hook_app
+
+
+@hook_app.command("install")
+def hook_install() -> None:
+    """
+    Install the post-checkout git hook.
+    """
+    git_dir = get_git_dir()
+    if git_dir is None:
+        console.print("[red]Error:[/] Not inside a git repository.")
+        raise typer.Exit(1)
+
+    try:
+        install_hook(git_dir)
+        console.print("[green]Hook installed.[/]")
+    except GitDbError as e:
+        console.print(f"[red]Error:[/] {e}")
+        raise typer.Exit(1) from e
+
+
+@hook_app.command("remove")
+def hook_remove() -> None:
+    """
+    Remove the post-checkout git hook.
+    """
+    git_dir = get_git_dir()
+    if git_dir is None:
+        console.print("[red]Error:[/] Not inside a git repository.")
+        raise typer.Exit(1)
+
+    try:
+        remove_hook(git_dir)
+        console.print("[green]Hook removed.[/]")
+    except GitDbError as e:
+        console.print(f"[red]Error:[/] {e}")
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def disable() -> None:
+    """
+    Temporarily disable git-db. Hook will skip all operations.
+    """
+    git_dir = get_git_dir()
+    if git_dir is None:
+        console.print("[red]Error:[/] Not inside a git repository.")
+        raise typer.Exit(1)
+
+    disabled_file = git_dir / "git-db" / "disabled"
+    disabled_file.parent.mkdir(parents=True, exist_ok=True)
+    disabled_file.touch()
+    console.print(
+        "[yellow]git-db disabled.[/] Run [cyan]git-db enable[/] to re-enable."
+    )
+
+
+@app.command()
+def enable() -> None:
+    """
+    Re-enable git-db after it was disabled.
+    """
+    git_dir = get_git_dir()
+    if git_dir is None:
+        console.print("[red]Error:[/] Not inside a git repository.")
+        raise typer.Exit(1)
+
+    disabled_file = git_dir / "git-db" / "disabled"
+    if disabled_file.exists():
+        disabled_file.unlink()
+        console.print("[green]git-db enabled.[/]")
+    else:
+        console.print("[dim]git-db is already enabled.[/]")
+
+
+@app.command("_hook-dispatch", hidden=True)
+def hook_dispatch(
+    prev_head: str,
+    new_head: str,
+    is_branch: str,
+) -> None:
+    """
+    Internal command called by the post-checkout hook.
+    """
+    try:
+        git_dir = get_git_dir()
+        if git_dir is None:
+            return
+
+        config = load_config()
+        handle_post_checkout(prev_head, is_branch, config)
+
+    except Exception as e:
+        console.print(f"[yellow]git-db warning:[/] {e}")