firebird-admin 1.0.1__tar.gz

firebird_admin-1.0.1/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: firebird-admin
+Version: 1.0.1
+Summary: A pgAdmin-style web administration and development tool for Firebird SQL
+Author: fbadmin contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mariuz/fbadmin
+Project-URL: Documentation, https://mariuz.github.io/fbadmin/
+Project-URL: Issues, https://github.com/mariuz/fbadmin/issues
+Keywords: firebird,database,admin,sql,pgadmin
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database :: Front-Ends
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.27
+Requires-Dist: pydantic>=2.5
+Requires-Dist: firebirdsql>=1.4.5
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: cryptography>=42
+Requires-Dist: argon2-cffi>=23.1
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: hypothesis>=6.100; extra == "dev"
+Requires-Dist: ldap3>=2.9; extra == "dev"
+Provides-Extra: ai
+Requires-Dist: anthropic>=1.0; extra == "ai"
+Provides-Extra: ldap
+Requires-Dist: ldap3>=2.9; extra == "ldap"
+Provides-Extra: legacy-auth
+Requires-Dist: passlib>=1.7; extra == "legacy-auth"
+Provides-Extra: native
+Requires-Dist: firebird-driver>=1.10; extra == "native"
+Provides-Extra: desktop
+Requires-Dist: pywebview>=5.0; extra == "desktop"
+
+# fbadmin
+
+A pgAdmin-style web administration and development tool for Firebird SQL (3.0, 4.0, 5.0):
+object explorer, DDL extraction, a query tool with plans and transactions, an editable data
+grid, live monitoring and backup/restore. No Firebird client library needed.
+
+```bash
+pip install firebird-admin
+fbadmin                 # starts on http://localhost:5050 and opens your browser
+fbadmin-desktop         # the same in a native window (pip install "firebird-admin[desktop]")
+```
+
+Options: `--host`, `--port`, `--no-browser`, `--log-level`, `--log-format json`.
+
+- Documentation: https://mariuz.github.io/fbadmin/
+- Source, issues and roadmap: https://github.com/mariuz/fbadmin
+- Docker image: `ghcr.io/mariuz/fbadmin`
+
+fbadmin sends no telemetry. Without server mode it has no login screen and listens on
+127.0.0.1 only.

firebird_admin-1.0.1/README.md

@@ -0,0 +1,20 @@
+# fbadmin
+
+A pgAdmin-style web administration and development tool for Firebird SQL (3.0, 4.0, 5.0):
+object explorer, DDL extraction, a query tool with plans and transactions, an editable data
+grid, live monitoring and backup/restore. No Firebird client library needed.
+
+```bash
+pip install firebird-admin
+fbadmin                 # starts on http://localhost:5050 and opens your browser
+fbadmin-desktop         # the same in a native window (pip install "firebird-admin[desktop]")
+```
+
+Options: `--host`, `--port`, `--no-browser`, `--log-level`, `--log-format json`.
+
+- Documentation: https://mariuz.github.io/fbadmin/
+- Source, issues and roadmap: https://github.com/mariuz/fbadmin
+- Docker image: `ghcr.io/mariuz/fbadmin`
+
+fbadmin sends no telemetry. Without server mode it has no login screen and listens on
+127.0.0.1 only.

firebird_admin-1.0.1/fbadmin/__init__.py

@@ -0,0 +1,7 @@
+"""fbadmin - a pgAdmin-style administration tool for Firebird SQL."""
+
+__version__ = "1.0.1"
+
+from . import driver_patches as _driver_patches  # noqa: E402
+
+_driver_patches.apply()

firebird_admin-1.0.1/fbadmin/__main__.py

@@ -0,0 +1,54 @@
+"""Command line entry point: ``fbadmin`` or ``python -m fbadmin``."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import threading
+import webbrowser
+
+import uvicorn
+
+from .config import settings
+from .logsetup import LEVELS, configure_logging
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(prog="fbadmin", description="Web administration tool for Firebird SQL")
+    p.add_argument("--host", default=settings.host, help="bind address (default %(default)s)")
+    p.add_argument("--port", type=int, default=settings.port, help="port (default %(default)s)")
+    p.add_argument("--no-browser", action="store_true", help="do not open a browser window")
+    p.add_argument("--reload", action="store_true", help="auto-reload on code changes (development)")
+    p.add_argument("--log-level", choices=LEVELS, default=None,
+                   help="log level (default $FBADMIN_LOG_LEVEL or info)")
+    p.add_argument("--log-format", choices=("text", "json"), default=None,
+                   help="log output format; json writes one object per line (default $FBADMIN_LOG_FORMAT or text)")
+    # --- security / server mode (docs/SECURITY.md)
+    p.add_argument("--server-mode", action="store_true",
+                   help="multi-user server mode with logins (same as FBADMIN_SERVER_MODE=1)")
+    p.add_argument("--ssl-certfile", help="serve HTTPS with this certificate (PEM)")
+    p.add_argument("--ssl-keyfile", help="private key for --ssl-certfile")
+    p.add_argument("--proxy-headers", action="store_true",
+                   help="trust X-Forwarded-Proto/For from --forwarded-allow-ips (behind a reverse proxy)")
+    p.add_argument("--forwarded-allow-ips", default=os.environ.get("FORWARDED_ALLOW_IPS", "127.0.0.1"),
+                   help="proxy addresses trusted for X-Forwarded-* headers (default %(default)s)")
+    args = p.parse_args()
+    log_config = configure_logging(args.log_level, args.log_format)
+    if args.server_mode:
+        os.environ["FBADMIN_SERVER_MODE"] = "1"
+    https = bool(args.ssl_certfile)
+    if not args.no_browser:
+        host = "localhost" if args.host in ("0.0.0.0", "127.0.0.1") else args.host
+        url = f"{'https' if https else 'http'}://{host}:{args.port}/"
+        threading.Timer(1.5, lambda: webbrowser.open(url)).start()
+    extra = {}
+    if https:
+        extra.update(ssl_certfile=args.ssl_certfile, ssl_keyfile=args.ssl_keyfile)
+    if args.proxy_headers:
+        extra.update(proxy_headers=True, forwarded_allow_ips=args.forwarded_allow_ips)
+    uvicorn.run("fbadmin.app:app", host=args.host, port=args.port, reload=args.reload,
+                log_config=log_config, access_log=False, **extra)
+
+
+if __name__ == "__main__":
+    main()

firebird_admin-1.0.1/fbadmin/ai/__init__.py

@@ -0,0 +1,41 @@
+"""Opt-in AI assistant: explain plans, suggest indices, convert SQL from other dialects.
+
+Disabled unless ``FBADMIN_AI_PROVIDER`` is set. Only SQL text, plans and table DDL are
+sent to the provider — never table data. Providers are pluggable: register a class with
+``register_provider`` or via the ``fbadmin.ai_providers`` entry point group.
+"""
+
+from __future__ import annotations
+
+import os
+from importlib.metadata import entry_points
+
+from .providers import AIProvider, AnthropicProvider, AIUnavailable
+
+_PROVIDERS: dict[str, type[AIProvider]] = {"anthropic": AnthropicProvider}
+
+
+def register_provider(name: str, cls: type[AIProvider]) -> None:
+    _PROVIDERS[name] = cls
+
+
+def _load_entry_points() -> None:
+    try:
+        for ep in entry_points(group="fbadmin.ai_providers"):
+            _PROVIDERS.setdefault(ep.name, ep.load())
+    except Exception:  # noqa: BLE001 - a broken plugin must not break the app
+        pass
+
+
+def get_provider() -> AIProvider | None:
+    name = os.environ.get("FBADMIN_AI_PROVIDER", "").strip().lower()
+    if not name or name == "none":
+        return None
+    _load_entry_points()
+    cls = _PROVIDERS.get(name)
+    if cls is None:
+        raise AIUnavailable(f"Unknown AI provider {name!r}; available: {', '.join(sorted(_PROVIDERS))}")
+    return cls()
+
+
+__all__ = ["AIProvider", "AIUnavailable", "AnthropicProvider", "get_provider", "register_provider"]

firebird_admin-1.0.1/fbadmin/ai/providers.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import os
+
+
+class AIUnavailable(Exception):
+    """The assistant is not configured or the provider failed."""
+
+
+class AIProvider:
+    """Interface for assistant backends."""
+
+    name = "base"
+
+    def complete(self, system: str, prompt: str) -> str:  # pragma: no cover - interface
+        raise NotImplementedError
+
+    def describe(self) -> dict:
+        return {"provider": self.name}
+
+
+class AnthropicProvider(AIProvider):
+    """Claude via the official Anthropic SDK (``pip install firebird-admin[ai]``).
+
+    Credentials come from the SDK's normal resolution (ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN,
+    an ``ant auth login`` profile, ...). Model: FBADMIN_AI_MODEL (default claude-opus-5-5).
+    """
+
+    name = "anthropic"
+
+    def __init__(self) -> None:
+        try:
+            import anthropic
+        except ImportError as exc:
+            raise AIUnavailable("The 'anthropic' package is not installed: pip install 'firebird-admin[ai]'") from exc
+        self._anthropic = anthropic
+        self.model = os.environ.get("FBADMIN_AI_MODEL", "claude-opus-5-5")
+        self.effort = os.environ.get("FBADMIN_AI_EFFORT", "high")
+        self.client = anthropic.Anthropic()
+
+    def describe(self) -> dict:
+        return {"provider": self.name, "model": self.model}
+
+    def complete(self, system: str, prompt: str) -> str:
+        a = self._anthropic
+        try:
+            # Server-side fallback: if a safety classifier declines, the API re-runs the
+            # request on a fallback model inside the same call.
+            with self.client.beta.messages.stream(
+                model=self.model,
+                max_tokens=16000,
+                system=system,
+                output_config={"effort": self.effort},
+                betas=["server-side-fallback-2026-07-01"],
+                fallbacks="default",
+                messages=[{"role": "user", "content": prompt}],
+            ) as stream:
+                msg = stream.get_final_message()
+        except a.AuthenticationError as exc:
+            raise AIUnavailable("Anthropic credentials are missing or invalid (set ANTHROPIC_API_KEY)") from exc
+        except a.RateLimitError as exc:
+            raise AIUnavailable("Rate limited by the Anthropic API; try again shortly") from exc
+        except a.APIStatusError as exc:
+            raise AIUnavailable(f"Anthropic API error {exc.status_code}: {exc.message}") from exc
+        except a.APIConnectionError as exc:
+            raise AIUnavailable("Cannot reach the Anthropic API (network)") from exc
+        if msg.stop_reason == "refusal":
+            raise AIUnavailable("The model declined this request")
+        text = "".join(b.text for b in msg.content if b.type == "text").strip()
+        if msg.stop_reason == "max_tokens":
+            text += "\n\n(answer truncated)"
+        return text

firebird_admin-1.0.1/fbadmin/api/__init__.py

@@ -0,0 +1,43 @@
+"""API routers. Feature modules add themselves to ROUTERS (one line each, to merge cleanly)."""
+
+from fastapi import APIRouter
+
+from . import ai  # noqa: I001 - one import per line keeps parallel branches mergeable
+from . import databases
+from . import jobs
+from . import maintenance
+from . import query
+from . import schedules
+from . import servers
+from . import trace
+from . import metrics
+from . import monitoring
+from . import replication
+from . import version as version_api
+from . import object_dialogs
+from . import schema
+from . import admin
+from . import auth
+from . import fbsecurity
+
+ROUTERS: list[APIRouter] = [
+    servers.router,
+    databases.router,
+    query.router,
+    jobs.router,
+    ai.router,
+    maintenance.router,
+    trace.router,
+    schedules.router,
+    monitoring.router,
+    monitoring.settings_router,
+    metrics.router,
+    replication.router,
+    replication.conf_router,
+    version_api.router,
+    object_dialogs.router,
+    schema.router,
+    auth.router,
+    admin.router,
+    fbsecurity.router,
+]

firebird_admin-1.0.1/fbadmin/api/admin.py

@@ -0,0 +1,84 @@
+"""fbadmin user administration and the audit log viewer (administrators only)."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Query
+from pydantic import BaseModel
+
+from ..security.core import require_admin
+from ..security.errors import SecurityError
+from .deps import get_state
+
+router = APIRouter(prefix="/api/admin", tags=["admin"])
+
+
+class UserIn(BaseModel):
+    username: str
+    email: str | None = None
+    password: str | None = None
+    role: str = "user"
+    active: bool = True
+    auth_source: str = "internal"
+
+
+class UserUpdate(BaseModel):
+    email: str | None = None
+    password: str | None = None
+    role: str | None = None
+    active: bool | None = None
+
+
+def _server_mode_admin():
+    p = require_admin()
+    if p is None:
+        raise SecurityError(400, "User accounts exist only in server mode", "desktop_mode")
+    return p
+
+
+@router.get("/users")
+def list_users():
+    _server_mode_admin()
+    return get_state().security.db.list_users()
+
+
+@router.post("/users", status_code=201)
+def create_user(body: UserIn):
+    _server_mode_admin()
+    sec = get_state().security
+    if body.auth_source not in ("internal", "ldap", "proxy") and not body.auth_source.startswith("oidc:"):
+        raise SecurityError(400, f"Unknown authentication source {body.auth_source!r}", "bad_source")
+    user = sec.create_user(body.username, email=body.email, password=body.password, role=body.role,
+                           auth_source=body.auth_source, active=body.active)
+    return {k: v for k, v in user.items() if k not in ("password_hash", "vault")}
+
+
+@router.put("/users/{user_id}")
+def update_user(user_id: int, body: UserUpdate):
+    p = _server_mode_admin()
+    user = get_state().security.update_user(user_id, body.model_dump(exclude_unset=True), p)
+    return {k: v for k, v in user.items() if k not in ("password_hash", "vault")}
+
+
+@router.delete("/users/{user_id}", status_code=204)
+def delete_user(user_id: int):
+    p = _server_mode_admin()
+    get_state().security.delete_user(user_id, p)
+
+
+@router.get("/audit")
+def audit(
+    limit: int = Query(100, ge=1, le=1000),
+    offset: int = Query(0, ge=0),
+    username: str | None = None,
+    server: str | None = None,
+    q: str | None = None,
+    success: bool | None = None,
+    since: float | None = None,
+    until: float | None = None,
+    category: str | None = None,
+):
+    require_admin()
+    sec = get_state().security
+    out = sec.db.query_audit(limit=limit, offset=offset, username=username, server=server, text=q,
+                             success=success, since=since, until=until, category=category) if sec.db.exists else {"total": 0, "rows": []}
+    return {**out, "enabled": sec.audit.enabled}

firebird_admin-1.0.1/fbadmin/api/ai.py

@@ -0,0 +1,117 @@
+"""AI assistant endpoints (opt-in, see fbadmin/ai)."""
+
+from __future__ import annotations
+
+import re
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from ..ai import AIUnavailable, get_provider
+from ..metadata import Catalog
+from ..query import explain
+from ..sqlsplit import bind_params
+from .deps import get_state
+
+router = APIRouter(prefix="/api/ai", tags=["ai"])
+
+SYSTEM = (
+    "You are a Firebird SQL expert embedded in fbadmin, a database administration tool. "
+    "Answer for Firebird {version} specifically (its SQL dialect, PSQL, plans and index behaviour). "
+    "Be concise and practical: short explanation, then concrete SQL in ```sql blocks when relevant. "
+    "Never invent tables or columns that are not in the provided DDL; say what is missing instead."
+)
+
+TASKS = {
+    "explain_plan": "Explain this query's execution plan in plain language. Point out full table scans "
+                    "(NATURAL / Full Scan), sorts and joins that could be slow, and why the optimizer chose them.",
+    "suggest_indexes": "Suggest indices (CREATE INDEX statements) that would make this query faster, given the plan "
+                       "and the table definitions. Mention selectivity concerns and existing indices that already cover it. "
+                       "If no index would help, say so.",
+    "convert_sql": "Convert the following SQL from {dialect} to Firebird SQL. Output the converted SQL in one ```sql block, "
+                   "then list the changes you made (e.g. LIMIT -> FETCH FIRST/ROWS, AUTO_INCREMENT -> IDENTITY, "
+                   "string concatenation, date functions, data types).",
+    "explain_error": "Explain this Firebird error for the given SQL and show the corrected SQL.",
+    "ask": "Answer the user's question about this SQL / database.",
+}
+
+
+class AskIn(BaseModel):
+    task: str
+    sql: str = ""
+    question: str = ""
+    error: str = ""
+    dialect: str = "MySQL"
+    server_id: str | None = None
+    database_id: str | None = None
+
+
+@router.get("/status")
+def status():
+    try:
+        p = get_provider()
+    except AIUnavailable as exc:
+        return {"enabled": False, "reason": str(exc)}
+    if p is None:
+        return {"enabled": False, "reason": "Set FBADMIN_AI_PROVIDER=anthropic to enable the assistant"}
+    return {"enabled": True, **p.describe()}
+
+
+def _context(server_id: str, db_id: str, sql: str, with_plan: bool) -> tuple[str, str]:
+    """Plan + DDL of the tables the statement touches; and the engine version."""
+    parts: list[str] = []
+    with get_state().manager.meta(server_id, db_id) as conn:
+        cat = Catalog(conn)
+        version = cat.engine_version
+        names: list[str] = []
+        if with_plan and sql.strip():
+            bound, _ = bind_params(sql.strip().rstrip(";"), [0])
+            try:
+                plan = explain(conn, bound)
+                detailed = explain(conn, bound, detailed=True)
+                parts.append(f"Plan:\n{plan}\n\nDetailed plan:\n{detailed}")
+                names += re.findall(r'Table (?:"[^"]+"\.)?"([^"]+)"', detailed or "")  # FB6: "SCHEMA"."T"
+            except Exception as exc:  # noqa: BLE001
+                parts.append(f"(could not prepare the statement: {exc})")
+        tables = {r["name"] for r in cat.list_objects("tables")} | {r["name"] for r in cat.list_objects("views")}
+        names += [w for w in re.findall(r'[A-Za-z_][A-Za-z0-9_$]*|"[^"]+"', sql) if w.strip('"').upper() in tables or w.strip('"') in tables]
+        seen = []
+        for n in names:
+            n = n.strip('"')
+            n = n if n in tables else n.upper()
+            if n in tables and n not in seen:
+                seen.append(n)
+        for n in seen[:12]:
+            otype = "tables" if n in {r["name"] for r in cat.list_objects("tables")} else "views"
+            try:
+                parts.append(cat.get_object(otype, n)["ddl"])
+            except Exception:  # noqa: BLE001
+                pass
+    return "\n\n".join(parts), version
+
+
+@router.post("/ask")
+def ask(body: AskIn):
+    try:
+        provider = get_provider()
+        if provider is None:
+            return JSONResponse(status_code=400, content={"detail": "AI assistant is disabled (FBADMIN_AI_PROVIDER not set)"})
+        if body.task not in TASKS:
+            return JSONResponse(status_code=400, content={"detail": f"Unknown task {body.task!r}"})
+        ctx, version = "", "3.0+"
+        if body.server_id and body.database_id and body.task != "convert_sql":
+            ctx, version = _context(body.server_id, body.database_id, body.sql,
+                                    with_plan=body.task in ("explain_plan", "suggest_indexes"))
+        prompt = TASKS[body.task].format(dialect=body.dialect)
+        if body.question:
+            prompt += f"\n\nQuestion: {body.question}"
+        if body.error:
+            prompt += f"\n\nError:\n{body.error}"
+        prompt += f"\n\nSQL:\n```sql\n{body.sql}\n```"
+        if ctx:
+            prompt += f"\n\nContext from the database:\n{ctx}"
+        answer = provider.complete(SYSTEM.format(version=version or "3.0+"), prompt)
+        return {"answer": answer, **provider.describe()}
+    except AIUnavailable as exc:
+        return JSONResponse(status_code=503, content={"detail": str(exc)})