sql-harness 0.1.0__py3-none-any.whl

sql_harness/config.py

@@ -0,0 +1,241 @@
+"""TOML configuration for sql-harness.
+
+Schema (lives at ~/.config/sql-harness/connections.toml by default):
+
+    default_workspace = "local_pg"          # optional, name of a connection
+    [pool_defaults]
+    size = 5
+    recycle = 3600
+    pre_ping = true
+    echo = false
+
+    [[connections]]
+    name = "local_pg"
+    driver = "postgres"
+    url = "postgresql+psycopg://user:pw@host:5432/db"
+    description = "..."
+    pool_size = 5
+    pool_recycle = 3600
+    pre_ping = true
+    echo = false
+    application_name = "sql-harness"
+
+${env:VAR} in `url` is expanded from the process environment.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import tomllib
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any
+
+# Match ${env:NAME} placeholders inside URL strings.
+_ENV_RE = re.compile(r"\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+@dataclass
+class PoolConfig:
+    """SQLAlchemy QueuePool knobs. Match URL is implied (`QueuePool`)."""
+
+    size: int = 5
+    recycle: int = 3600
+    pre_ping: bool = True
+    echo: bool = False
+
+    def sqlalchemy_kwargs(self) -> dict[str, Any]:
+        """Subset of kwargs accepted by sqlalchemy.create_engine()."""
+        return {
+            "pool_size": self.size,
+            "pool_recycle": self.recycle,
+            "pool_pre_ping": self.pre_ping,
+            "echo": self.echo,
+        }
+
+
+@dataclass
+class ConnectionConfig:
+    """A single named connection profile."""
+
+    name: str
+    driver: str                                # postgres | mysql | redis
+    url: str
+    description: str = ""
+    pool: PoolConfig = field(default_factory=PoolConfig)
+    application_name: str = "sql-harness"
+
+    def masked_url(self) -> str:
+        """Return the URL with password redacted."""
+        return _ENV_RE.sub(lambda m: os.environ.get(m.group(1), ""), _mask_password(self.url))
+
+
+@dataclass
+class ConnectionsConfig:
+    """Top-level config; one TOML file."""
+
+    default_workspace: str = ""
+    pool_defaults: PoolConfig = field(default_factory=PoolConfig)
+    connections: list[ConnectionConfig] = field(default_factory=list)
+
+    def get(self, name: str) -> ConnectionConfig:
+        for c in self.connections:
+            if c.name == name:
+                return c
+        raise KeyError(f"no connection named {name!r}")
+
+    def names(self) -> list[str]:
+        return [c.name for c in self.connections]
+
+    def apply_pool_defaults(self) -> None:
+        """For any connection that didn't override pool fields, use defaults."""
+        for c in self.connections:
+            if c.pool == PoolConfig():                # pure default
+                c.pool = replace(self.pool_defaults)
+
+
+# --- TOML I/O ---------------------------------------------------------------
+
+
+def _expand_env(value: str) -> str:
+    """Replace ${env:VAR} with the value of $VAR (or empty if unset)."""
+    return _ENV_RE.sub(lambda m: os.environ.get(m.group(1), ""), value)
+
+
+def _mask_password(url: str) -> str:
+    """Replace the userinfo password with *** (best-effort)."""
+    # Format: scheme://user:password@host/...
+    if "@" not in url:
+        return url
+    head, tail = url.split("@", 1)
+    if "://" not in head:
+        return url
+    scheme, creds = head.split("://", 1)
+    if ":" in creds:
+        user, _ = creds.split(":", 1)
+        return f"{scheme}://{user}:***@{tail}"
+    return url
+
+
+def load(path: Path) -> ConnectionsConfig:
+    """Load and parse connections.toml. Returns empty config if file missing."""
+    if not path.exists():
+        return ConnectionsConfig()
+    with path.open("rb") as f:
+        raw = tomllib.load(f)
+    return _from_dict(raw)
+
+
+def save(cfg: ConnectionsConfig, path: Path) -> None:
+    """Serialize to TOML. Pure stdlib (manual writer — no tomllib writer in 3.11)."""
+    lines: list[str] = []
+    if cfg.default_workspace:
+        lines.append(f'default_workspace = "{_toml_str(cfg.default_workspace)}"')
+        lines.append("")
+
+    pd = cfg.pool_defaults
+    lines.append("[pool_defaults]")
+    lines.append(f"size = {pd.size}")
+    lines.append(f"recycle = {pd.recycle}")
+    lines.append(f"pre_ping = {'true' if pd.pre_ping else 'false'}")
+    lines.append(f"echo = {'true' if pd.echo else 'false'}")
+    lines.append("")
+
+    for c in cfg.connections:
+        lines.append("[[connections]]")
+        lines.append(f'name = "{_toml_str(c.name)}"')
+        lines.append(f'driver = "{_toml_str(c.driver)}"')
+        lines.append(f'url = "{_toml_str(c.url)}"')
+        if c.description:
+            lines.append(f'description = "{_toml_str(c.description)}"')
+        if c.pool.size != cfg.pool_defaults.size:
+            lines.append(f"pool_size = {c.pool.size}")
+        if c.pool.recycle != cfg.pool_defaults.recycle:
+            lines.append(f"pool_recycle = {c.pool.recycle}")
+        if c.pool.pre_ping != cfg.pool_defaults.pre_ping:
+            lines.append(f"pre_ping = {'true' if c.pool.pre_ping else 'false'}")
+        if c.pool.echo != cfg.pool_defaults.echo:
+            lines.append(f"echo = {'true' if c.pool.echo else 'false'}")
+        if c.application_name != "sql-harness":
+            lines.append(f'application_name = "{_toml_str(c.application_name)}"')
+        lines.append("")
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(lines), encoding="utf-8")
+
+
+def _toml_str(s: str) -> str:
+    """Escape a string for embedding in a TOML basic string."""
+    return s.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _from_dict(raw: dict[str, Any]) -> ConnectionsConfig:
+    """Parse the loaded TOML dict into dataclasses + env-expand URLs."""
+    pd_raw = raw.get("pool_defaults") or {}
+    pool_defaults = PoolConfig(
+        size=int(pd_raw.get("size", 5)),
+        recycle=int(pd_raw.get("recycle", 3600)),
+        pre_ping=bool(pd_raw.get("pre_ping", True)),
+        echo=bool(pd_raw.get("echo", False)),
+    )
+
+    conns: list[ConnectionConfig] = []
+    for entry in raw.get("connections", []) or []:
+        p_raw = entry.get("pool") or {}
+        pool = PoolConfig(
+            size=int(p_raw.get("size", pool_defaults.size)),
+            recycle=int(p_raw.get("recycle", pool_defaults.recycle)),
+            pre_ping=bool(p_raw.get("pre_ping", pool_defaults.pre_ping)),
+            echo=bool(p_raw.get("echo", pool_defaults.echo)),
+        )
+        # Top-level pool_* keys (per the schema example) override the nested block.
+        if "pool_size" in entry:
+            pool.size = int(entry["pool_size"])
+        if "pool_recycle" in entry:
+            pool.recycle = int(entry["pool_recycle"])
+        if "pre_ping" in entry:
+            pool.pre_ping = bool(entry["pre_ping"])
+        if "echo" in entry:
+            pool.echo = bool(entry["echo"])
+
+        conns.append(
+            ConnectionConfig(
+                name=str(entry["name"]),
+                driver=str(entry["driver"]),
+                url=_expand_env(str(entry["url"])),
+                description=str(entry.get("description", "")),
+                pool=pool,
+                application_name=str(entry.get("application_name", "sql-harness")),
+            )
+        )
+
+    return ConnectionsConfig(
+        default_workspace=str(raw.get("default_workspace", "")),
+        pool_defaults=pool_defaults,
+        connections=conns,
+    )
+
+
+def example_config() -> ConnectionsConfig:
+    """A safe-to-write starter config (no real secrets)."""
+    return ConnectionsConfig(
+        default_workspace="local_pg",
+        pool_defaults=PoolConfig(),
+        connections=[
+            ConnectionConfig(
+                name="local_pg",
+                driver="postgres",
+                url="postgresql+psycopg://postgres:postgres@localhost:5432/postgres",
+                description="Local PostgreSQL for dev",
+                pool=PoolConfig(size=5),
+            ),
+            ConnectionConfig(
+                name="local_mysql",
+                driver="mysql",
+                url="mysql+pymysql://root:root@localhost:3306/mysql?charset=utf8mb4",
+                description="Local MySQL for dev",
+                pool=PoolConfig(size=5),
+            ),
+        ],
+    )

sql_harness/drivers/__init__.py

@@ -0,0 +1,59 @@
+"""Driver abstraction for sql-harness.
+
+A Driver wraps a SQLAlchemy Engine with dialect-specific helpers
+(`list_tables`, `describe`, `quote_ident`). Adding a new backend
+means adding one file here implementing the `Driver` protocol.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from sqlalchemy import Engine
+
+
+class Driver(Protocol):
+    """Protocol every backend implements."""
+
+    name: str
+
+    def make_engine(self, url: str, pool: "PoolConfig") -> Engine:
+        """Create a SQLAlchemy Engine with the given pool config."""
+
+    def list_tables(self, engine: Engine, schema: str | None) -> list[str]:
+        """Return table names (and views) visible in the given schema."""
+
+    def describe(
+        self, engine: Engine, table: str, schema: str | None
+    ) -> list[dict]:
+        """Return column metadata: [{name, type, nullable, default}, ...]."""
+
+    def quote_ident(self, ident: str) -> str:
+        """Safely quote an identifier for the dialect."""
+
+
+def get_driver(name: str) -> Driver:
+    """Look up a driver by its short name."""
+    if name == "postgres":
+        from .postgres import PostgresDriver
+
+        return PostgresDriver()
+    if name == "mysql":
+        from .mysql import MysqlDriver
+
+        return MysqlDriver()
+    if name == "redis":
+        from .redis import RedisDriver
+
+        return RedisDriver()
+    if name == "sqlite":
+        from .sqlite import SqliteDriver
+
+        return SqliteDriver()
+    if name in ("ssh", "ssh+password", "ssh+key"):
+        from .ssh import SshDriver
+
+        return SshDriver()
+    raise ValueError(
+        f"unknown driver: {name!r} (known: postgres, mysql, redis, sqlite, ssh)"
+    )

sql_harness/drivers/mysql.py

@@ -0,0 +1,43 @@
+"""MySQL driver (PyMySQL via SQLAlchemy)."""
+
+from __future__ import annotations
+
+from sqlalchemy import Engine, create_engine, inspect, text
+
+
+class MysqlDriver:
+    name = "mysql"
+
+    def make_engine(self, url: str, pool) -> Engine:
+        if not url.startswith("mysql+pymysql://"):
+            raise ValueError(
+                f"MySQL URL must start with mysql+pymysql:// (got {url[:30]!r})"
+            )
+        return create_engine(url, **pool.sqlalchemy_kwargs())
+
+    def list_tables(self, engine: Engine, schema: str | None) -> list[str]:
+        insp = inspect(engine)
+        return sorted(
+            insp.get_table_names(schema=schema) + insp.get_view_names(schema=schema)
+        )
+
+    def describe(self, engine: Engine, table: str, schema: str | None) -> list[dict]:
+        insp = inspect(engine)
+        cols = insp.get_columns(table, schema=schema)
+        return [
+            {
+                "name": c["name"],
+                "type": str(c["type"]),
+                "nullable": bool(c.get("nullable", True)),
+                "default": str(c.get("default")) if c.get("default") is not None else None,
+            }
+            for c in cols
+        ]
+
+    def quote_ident(self, ident: str) -> str:
+        # MySQL: backticks; escape embedded backticks.
+        return "`" + ident.replace("`", "``") + "`"
+
+    def server_version(self, engine: Engine) -> str:
+        with engine.connect() as conn:
+            return str(conn.execute(text("SELECT VERSION()")).scalar())

sql_harness/drivers/postgres.py

@@ -0,0 +1,55 @@
+"""PostgreSQL driver (psycopg 3 via SQLAlchemy)."""
+
+from __future__ import annotations
+
+from sqlalchemy import Engine, create_engine, inspect, text
+
+
+class PostgresDriver:
+    name = "postgres"
+
+    def make_engine(self, url: str, pool) -> Engine:
+        # Accept all three SQLAlchemy-recognized PostgreSQL URL prefixes:
+        #   postgresql+psycopg://  (explicit dialect — preferred)
+        #   postgresql://          (SQLAlchemy maps to default psycopg driver)
+        #   postgres://            (short alias SQLAlchemy also accepts)
+        # Normalize to the explicit dialect form for determinism.
+        if url.startswith("postgresql+psycopg://"):
+            pass
+        elif url.startswith("postgresql://"):
+            url = "postgresql+psycopg://" + url[len("postgresql://"):]
+        elif url.startswith("postgres://"):
+            url = "postgresql+psycopg://" + url[len("postgres://"):]
+        else:
+            raise ValueError(
+                f"PostgreSQL URL must start with postgres:// or postgresql:// "
+                f"(got {url[:30]!r})"
+            )
+        return create_engine(url, **pool.sqlalchemy_kwargs())
+
+    def list_tables(self, engine: Engine, schema: str | None) -> list[str]:
+        insp = inspect(engine)
+        return sorted(
+            insp.get_table_names(schema=schema) + insp.get_view_names(schema=schema)
+        )
+
+    def describe(self, engine: Engine, table: str, schema: str | None) -> list[dict]:
+        insp = inspect(engine)
+        cols = insp.get_columns(table, schema=schema)
+        return [
+            {
+                "name": c["name"],
+                "type": str(c["type"]),
+                "nullable": bool(c.get("nullable", True)),
+                "default": str(c.get("default")) if c.get("default") is not None else None,
+            }
+            for c in cols
+        ]
+
+    def quote_ident(self, ident: str) -> str:
+        # PostgreSQL standard: double-quote, escape embedded double-quotes.
+        return '"' + ident.replace('"', '""') + '"'
+
+    def server_version(self, engine: Engine) -> str:
+        with engine.connect() as conn:
+            return str(conn.execute(text("SELECT version()")).scalar())

sql_harness/drivers/redis.py

@@ -0,0 +1,33 @@
+"""Redis driver (stub).
+
+Placeholder for the future extension. To enable Redis:
+
+1. `uv add "redis>=5.0,<6"`
+2. Implement the Driver protocol below (sync Redis with ConnectionPool).
+3. Register it in `drivers/__init__.py:get_driver` (already wired).
+
+Until then, `driver = "redis"` in connections.toml will raise NotImplementedError.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import Engine
+
+
+class RedisDriver:
+    name = "redis"
+
+    def make_engine(self, url: str, pool) -> Engine:
+        raise NotImplementedError(
+            "Redis driver is not yet implemented. "
+            "Add redis-py to deps and fill in drivers/redis.py."
+        )
+
+    def list_tables(self, engine: Engine, schema: str | None) -> list[str]:
+        raise NotImplementedError("Redis driver is not yet implemented.")
+
+    def describe(self, engine: Engine, table: str, schema: str | None) -> list[dict]:
+        raise NotImplementedError("Redis driver is not yet implemented.")
+
+    def quote_ident(self, ident: str) -> str:
+        raise NotImplementedError("Redis driver is not yet implemented.")

sql_harness/drivers/sqlite.py

@@ -0,0 +1,39 @@
+"""SQLite driver — useful for local dev + tests.
+
+Added as a built-in 4th driver so unit tests can use a real SQL backend
+without needing a Postgres or MySQL server.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import Engine, create_engine, inspect
+
+
+class SqliteDriver:
+    name = "sqlite"
+
+    def make_engine(self, url: str, pool) -> Engine:
+        # SQLite ignores most pool settings; StaticPool is fine for in-memory.
+        if not url.startswith("sqlite:"):
+            raise ValueError(f"SQLite URL must start with sqlite: (got {url[:30]!r})")
+        return create_engine(url, future=True)
+
+    def list_tables(self, engine: Engine, schema: str | None) -> list[str]:
+        insp = inspect(engine)
+        return sorted(insp.get_table_names(schema=schema))
+
+    def describe(self, engine: Engine, table: str, schema: str | None) -> list[dict]:
+        insp = inspect(engine)
+        cols = insp.get_columns(table, schema=schema)
+        return [
+            {
+                "name": c["name"],
+                "type": str(c["type"]),
+                "nullable": bool(c.get("nullable", True)),
+                "default": str(c.get("default")) if c.get("default") is not None else None,
+            }
+            for c in cols
+        ]
+
+    def quote_ident(self, ident: str) -> str:
+        return '"' + ident.replace('"', '""') + '"'