schemaingest 0.1.0__tar.gz

schemaingest-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jineth Bosilu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

schemaingest-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+graft tests
+global-exclude __pycache__ *.py[cod]

schemaingest-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: schemaingest
+Version: 0.1.0
+Summary: Introspect your PostgreSQL or MySQL/MariaDB schema through a web UI, without credentials leaving your machine.
+Author: Jineth Bosilu
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/JinethBosilu/SchemaIngest
+Project-URL: Web UI, https://jinethbosilu.github.io/SchemaIngest/
+Project-URL: Issues, https://github.com/JinethBosilu/SchemaIngest/issues
+Keywords: postgres,postgresql,mysql,mariadb,schema,introspection,erd,database,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: uvicorn[standard]>=0.24.0
+Requires-Dist: psycopg2-binary>=2.9.9
+Requires-Dist: PyMySQL[rsa]>=1.1
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: click>=8.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: httpx2>=2.0; extra == "dev"
+Dynamic: license-file
+
+# SchemaIngest
+
+**A "gitingest"-style tool for databases.** Browse your PostgreSQL, MySQL or MariaDB schema in a web UI (tables,
+columns, keys, indexes and an interactive relationship diagram), and copy a compact,
+token-efficient description of it for an AI. Your credentials never leave your machine.
+
+This package is the **local agent**. It runs on `127.0.0.1`, connects to your database
+read-only, and serves the schema to the web UI at
+<https://jinethbosilu.github.io/SchemaIngest/>.
+
+## Install
+
+```bash
+pipx install schemaingest      # or: pip install schemaingest
+```
+
+Requires Python 3.10+.
+
+## Use it with the web UI
+
+```bash
+schemaingest agent
+```
+
+The terminal shows a 6-digit **pairing code**. Open
+<https://jinethbosilu.github.io/SchemaIngest/>, enter the code, then pick your database engine
+and enter its connection details. They go only to the agent on `localhost`.
+
+Chrome may ask whether the page can access devices on your local network. Allow it: that
+is the browser checking before a public site talks to the agent on `127.0.0.1`.
+
+## Use it without the web UI
+
+```bash
+# Full schema pack as JSON
+schemaingest pull --conn "postgresql://user:pass@localhost:5432/mydb" --out schema.json
+
+# Compact text, ready to paste into an AI
+schemaingest pull --conn "postgresql://user:pass@localhost:5432/mydb" --out schema.txt --format txt
+
+# MySQL or MariaDB: the scheme picks the engine
+schemaingest pull --conn "mysql://user:pass@localhost:3306/mydb" --out schema.txt --format txt
+```
+
+For PostgreSQL, `--schema` picks a schema other than `public`. In MySQL a database is a
+schema, so the database in the connection string is the one introspected. MySQL
+connection strings accept `?ssl-mode=` with MySQL's values (`DISABLED`, `PREFERRED`,
+`REQUIRED`, `VERIFY_CA`, `VERIFY_IDENTITY`).
+
+## Security
+
+- Binds to `127.0.0.1` only.
+- CORS allows only the GitHub Pages UI and local development origins.
+- A pairing code is required before any session is issued; sessions expire after 4 hours.
+- Connections are opened read-only.
+- Passwords are redacted from every printed error, and request bodies are never logged.
+
+## License
+
+MIT

schemaingest-0.1.0/README.md

@@ -0,0 +1,60 @@
+# SchemaIngest
+
+**A "gitingest"-style tool for databases.** Browse your PostgreSQL, MySQL or MariaDB schema in a web UI (tables,
+columns, keys, indexes and an interactive relationship diagram), and copy a compact,
+token-efficient description of it for an AI. Your credentials never leave your machine.
+
+This package is the **local agent**. It runs on `127.0.0.1`, connects to your database
+read-only, and serves the schema to the web UI at
+<https://jinethbosilu.github.io/SchemaIngest/>.
+
+## Install
+
+```bash
+pipx install schemaingest      # or: pip install schemaingest
+```
+
+Requires Python 3.10+.
+
+## Use it with the web UI
+
+```bash
+schemaingest agent
+```
+
+The terminal shows a 6-digit **pairing code**. Open
+<https://jinethbosilu.github.io/SchemaIngest/>, enter the code, then pick your database engine
+and enter its connection details. They go only to the agent on `localhost`.
+
+Chrome may ask whether the page can access devices on your local network. Allow it: that
+is the browser checking before a public site talks to the agent on `127.0.0.1`.
+
+## Use it without the web UI
+
+```bash
+# Full schema pack as JSON
+schemaingest pull --conn "postgresql://user:pass@localhost:5432/mydb" --out schema.json
+
+# Compact text, ready to paste into an AI
+schemaingest pull --conn "postgresql://user:pass@localhost:5432/mydb" --out schema.txt --format txt
+
+# MySQL or MariaDB: the scheme picks the engine
+schemaingest pull --conn "mysql://user:pass@localhost:3306/mydb" --out schema.txt --format txt
+```
+
+For PostgreSQL, `--schema` picks a schema other than `public`. In MySQL a database is a
+schema, so the database in the connection string is the one introspected. MySQL
+connection strings accept `?ssl-mode=` with MySQL's values (`DISABLED`, `PREFERRED`,
+`REQUIRED`, `VERIFY_CA`, `VERIFY_IDENTITY`).
+
+## Security
+
+- Binds to `127.0.0.1` only.
+- CORS allows only the GitHub Pages UI and local development origins.
+- A pairing code is required before any session is issued; sessions expire after 4 hours.
+- Connections are opened read-only.
+- Passwords are redacted from every printed error, and request bodies are never logged.
+
+## License
+
+MIT

schemaingest-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "schemaingest"
+dynamic = ["version"]
+description = "Introspect your PostgreSQL or MySQL/MariaDB schema through a web UI, without credentials leaving your machine."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Jineth Bosilu"}
+]
+keywords = ["postgres", "postgresql", "mysql", "mariadb", "schema", "introspection", "erd", "database", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Database",
+    "Topic :: Software Development :: Documentation",
+]
+dependencies = [
+    "fastapi>=0.104.0",
+    "uvicorn[standard]>=0.24.0",
+    "psycopg2-binary>=2.9.9",
+    "PyMySQL[rsa]>=1.1",  # rsa: MySQL 8's default caching_sha2_password login
+    "pydantic>=2.5.0",
+    "click>=8.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "httpx>=0.27",   # test client for older Starlette
+    "httpx2>=2.0",   # test client for Starlette 1.x
+]
+
+[project.urls]
+Homepage = "https://github.com/JinethBosilu/SchemaIngest"
+"Web UI" = "https://jinethbosilu.github.io/SchemaIngest/"
+Issues = "https://github.com/JinethBosilu/SchemaIngest/issues"
+
+[project.scripts]
+schemaingest = "schemaingest.cli:main"
+
+[tool.setuptools.dynamic]
+version = {attr = "schemaingest.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["schemaingest*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

schemaingest-0.1.0/schemaingest/__init__.py

@@ -0,0 +1,3 @@
+"""SchemaIngest — local database schema introspection agent."""
+
+__version__ = "0.1.0"

schemaingest-0.1.0/schemaingest/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as `python -m schemaingest`."""
+
+from schemaingest.cli import main
+
+if __name__ == "__main__":
+    main()

schemaingest-0.1.0/schemaingest/cli.py

@@ -0,0 +1,99 @@
+"""CLI entry point for SchemaIngest agent."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+
+from schemaingest import __version__
+from schemaingest.security import generate_pairing_code, redact_password, set_pairing_code
+
+WEB_UI_URL = "https://jinethbosilu.github.io/SchemaIngest/"
+
+
+def _banner(lines: list[str]) -> str:
+    """A box sized to its contents. Plain ASCII, so it lines up on any console
+    (Windows code pages included) - emoji are double-width and would not."""
+    width = max(len(line) for line in lines) + 4
+    rule = "+" + "-" * width + "+"
+    body = [f"|  {line.ljust(width - 4)}  |" for line in lines]
+    return "\n".join([rule, *body, rule])
+
+
+@click.group()
+@click.version_option(__version__, prog_name="schemaingest")
+def main():
+    """SchemaIngest — local database schema introspection agent."""
+
+
+@main.command()
+@click.option("--port", default=8420, show_default=True, help="Port to listen on (127.0.0.1 only).")
+def agent(port: int):
+    """Start the SchemaIngest agent server."""
+    import uvicorn
+
+    from schemaingest.server import create_app
+
+    # The agent only ever binds to loopback: it holds database credentials.
+    host = "127.0.0.1"
+    code = generate_pairing_code()
+    set_pairing_code(code)
+
+    click.echo("")
+    click.echo(_banner([
+        f"SchemaIngest Agent v{__version__}",
+        "",
+        f"Pairing code:  {code}",
+        "Enter this code in the web UI to connect.",
+        "",
+        f"Agent:   http://{host}:{port}",
+        f"Web UI:  {WEB_UI_URL}",
+    ]))
+    click.echo("")
+
+    uvicorn.run(create_app(), host=host, port=port, log_level="info")
+
+
+@main.command()
+@click.option(
+    "--conn", required=True,
+    help="Connection string: postgresql://user:pass@host/db or mysql://user:pass@host/db.",
+)
+@click.option("--out", required=True, type=click.Path(dir_okay=False), help="Output file path.")
+@click.option(
+    "--schema", default=None,
+    help="Schema to introspect. PostgreSQL: defaults to public. MySQL: the database in --conn.",
+)
+@click.option(
+    "--format", "fmt",
+    type=click.Choice(["json", "txt"]), default="json", show_default=True,
+    help="json: the full schema pack. txt: the compact text for pasting into an AI.",
+)
+def pull(conn: str, out: str, schema: str | None, fmt: str):
+    """Export the schema without the web UI."""
+    from schemaingest.introspect import introspect
+    from schemaingest.models import ConnectRequest
+    from schemaingest.renderers import render_schema_txt
+
+    click.echo(f"Connecting to: {redact_password(conn)}")
+
+    try:
+        pack = introspect(ConnectRequest(connectionString=conn, schema=schema))
+    except Exception as e:
+        click.echo(f"Connection failed: {redact_password(str(e))}", err=True)
+        sys.exit(1)
+
+    with open(out, "w", encoding="utf-8") as f:
+        if fmt == "txt":
+            f.write(render_schema_txt(pack))
+        else:
+            json.dump(pack.model_dump(by_alias=True), f, indent=2)
+
+    click.echo(f"Schema written to {out}")
+    click.echo(f"   Tables: {len(pack.tables)}, Relationships: {len(pack.relationships)}")
+
+
+if __name__ == "__main__":
+    main()

schemaingest-0.1.0/schemaingest/endpoints.py

@@ -0,0 +1,77 @@
+"""FastAPI route handlers."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+from fastapi.responses import JSONResponse
+
+from schemaingest.introspect import introspect
+from schemaingest.models import ConnectRequest, PairRequest, SchemaPack
+from schemaingest.renderers import render_erd_mermaid, render_schema_txt
+from schemaingest.security import (
+    rate_limit_dep,
+    redact_password,
+    require_session,
+    verify_pairing_code,
+)
+from schemaingest import __version__
+
+router = APIRouter()
+
+
+# Handlers are plain `def`: the database drivers block, so FastAPI runs them in its
+# threadpool instead of on the event loop.
+
+# ─── Health ───────────────────────────────────────────────────────────
+
+@router.get("/health")
+def health():
+    return {"status": "ok", "version": __version__}
+
+
+# ─── Pairing ──────────────────────────────────────────────────────────
+
+@router.post("/pair/start", dependencies=[Depends(rate_limit_dep)])
+def pair_start(body: PairRequest):
+    token = verify_pairing_code(body.code)
+    if token is None:
+        return JSONResponse(status_code=403, content={"detail": "Invalid pairing code"})
+    return {"sessionToken": token}
+
+
+# ─── Introspection ────────────────────────────────────────────────────
+
+def _do_introspect(req: ConnectRequest) -> SchemaPack:
+    """Shared introspection helper."""
+    try:
+        return introspect(req)
+    except Exception as e:
+        # Sanitise the error message to avoid leaking credentials
+        raise ValueError(redact_password(str(e))) from None
+
+
+@router.post("/introspect", dependencies=[Depends(rate_limit_dep)])
+def introspect_endpoint(body: ConnectRequest, _token: str = Depends(require_session)):
+    try:
+        pack = _do_introspect(body)
+    except ValueError as e:
+        return JSONResponse(status_code=400, content={"detail": str(e)})
+    return pack.model_dump(by_alias=True)
+
+
+@router.post("/render/schema.txt", dependencies=[Depends(rate_limit_dep)])
+def render_schema_txt_endpoint(body: ConnectRequest, _token: str = Depends(require_session)):
+    try:
+        pack = _do_introspect(body)
+    except ValueError as e:
+        return JSONResponse(status_code=400, content={"detail": str(e)})
+    return {"text": render_schema_txt(pack)}
+
+
+@router.post("/render/erd.mmd", dependencies=[Depends(rate_limit_dep)])
+def render_erd_mmd_endpoint(body: ConnectRequest, _token: str = Depends(require_session)):
+    try:
+        pack = _do_introspect(body)
+    except ValueError as e:
+        return JSONResponse(status_code=400, content={"detail": str(e)})
+    return {"mermaid": render_erd_mermaid(pack)}

schemaingest-0.1.0/schemaingest/introspect/__init__.py

@@ -0,0 +1,19 @@
+"""Schema introspection, one module per database engine."""
+
+from __future__ import annotations
+
+from schemaingest.models import ConnectRequest, SchemaPack
+
+
+def introspect(req: ConnectRequest) -> SchemaPack:
+    """Introspect the database a connect request names, whichever engine it is."""
+    # Drivers load on demand, so one engine's driver failing to import does
+    # not take the other engine down with it.
+    if req.resolved_engine() == "mysql":
+        from schemaingest.introspect.mysql import introspect_mysql
+
+        return introspect_mysql(req.to_mysql_params(), schema=req.resolved_schema())
+
+    from schemaingest.introspect.postgres import introspect_postgres
+
+    return introspect_postgres(req.to_dsn(), schema=req.resolved_schema())

schemaingest-0.1.0/schemaingest/introspect/common.py

@@ -0,0 +1,94 @@
+"""Pack assembly shared by every engine.
+
+Each engine reads its own catalog and hands over plain rows; turning those
+rows into columns, keys and relationships happens here, once."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Iterable, Optional, TypedDict
+
+from schemaingest import __version__
+from schemaingest.models import (
+    ColumnInfo,
+    ConstraintInfo,
+    DbMeta,
+    FkRef,
+    IndexInfo,
+    Relationship,
+    TableInfo,
+)
+
+
+class RawColumn(TypedDict):
+    name: str
+    type: str
+    nullable: bool
+    default: Optional[str]
+
+
+class RawForeignKey(TypedDict):
+    """One column pair of a foreign key; a composite key is several rows
+    sharing constraint_name, in key order."""
+    from_column: str
+    to_table: str
+    to_column: str
+    constraint_name: str
+
+
+def build_table(
+    tname: str,
+    schema: str,
+    columns: Iterable[RawColumn],
+    pk_cols: list[str],
+    fks: Iterable[RawForeignKey],
+    constraints: list[ConstraintInfo],
+    indexes: list[IndexInfo],
+) -> tuple[TableInfo, list[Relationship]]:
+    relationships: list[Relationship] = []
+    fk_map: dict[str, FkRef] = {}
+    for fk in fks:
+        # A column in two foreign keys keeps its first target for fkRef; every
+        # pairing is still listed in relationships.
+        fk_map.setdefault(fk["from_column"], FkRef(table=fk["to_table"], column=fk["to_column"]))
+        relationships.append(
+            Relationship(
+                fromTable=tname,
+                fromColumn=fk["from_column"],
+                toTable=fk["to_table"],
+                toColumn=fk["to_column"],
+                constraintName=fk["constraint_name"],
+            )
+        )
+
+    table = TableInfo(
+        name=tname,
+        schema=schema,
+        columns=[
+            ColumnInfo(
+                name=c["name"],
+                type=c["type"],
+                nullable=c["nullable"],
+                default=c["default"],
+                isPrimaryKey=c["name"] in pk_cols,
+                isForeignKey=c["name"] in fk_map,
+                fkRef=fk_map.get(c["name"]),
+            )
+            for c in columns
+        ],
+        primaryKey=pk_cols,
+        indexes=indexes,
+        constraints=constraints,
+    )
+    return table, relationships
+
+
+def make_meta(engine: str, db_name: str, db_version: str, schema: str) -> DbMeta:
+    return DbMeta(
+        engine=engine,
+        dbName=db_name,
+        dbVersion=db_version,
+        schema=schema,
+        generatedAt=datetime.now(timezone.utc).isoformat(),
+        agentVersion=__version__,
+    )