muscles-sql 1.0.0__py3-none-any.whl

muscles_sql/__init__.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .config import DatabaseConfig
+    from .config import SqlConnectionConfig
+    from .connections import SqlConnectionRegistry, UnknownSqlConnection
+    from .engine import EngineManager
+    from .mapping import map_model
+    from .providers import SqlResourceGeneratorProvider
+    from .query import FilterClause, JoinClause, QuerySpec
+    from .repository import SqlRepository
+    from .uow import UnitOfWork
+
+__all__ = [
+    "DatabaseConfig",
+    "SqlConnectionConfig",
+    "SqlConnectionRegistry",
+    "UnknownSqlConnection",
+    "EngineManager",
+    "map_model",
+    "SqlRepository",
+    "UnitOfWork",
+    "QuerySpec",
+    "FilterClause",
+    "JoinClause",
+    "SqlResourceGeneratorProvider",
+]
+
+
+def __getattr__(name: str):
+    if name == "DatabaseConfig":
+        from .config import DatabaseConfig
+
+        return DatabaseConfig
+    if name == "SqlConnectionConfig":
+        from .config import SqlConnectionConfig
+
+        return SqlConnectionConfig
+    if name == "SqlConnectionRegistry":
+        from .connections import SqlConnectionRegistry
+
+        return SqlConnectionRegistry
+    if name == "UnknownSqlConnection":
+        from .connections import UnknownSqlConnection
+
+        return UnknownSqlConnection
+    if name == "EngineManager":
+        from .engine import EngineManager
+
+        return EngineManager
+    if name == "map_model":
+        from .mapping import map_model
+
+        return map_model
+    if name == "SqlRepository":
+        from .repository import SqlRepository
+
+        return SqlRepository
+    if name == "UnitOfWork":
+        from .uow import UnitOfWork
+
+        return UnitOfWork
+    if name == "QuerySpec":
+        from .query import QuerySpec
+
+        return QuerySpec
+    if name == "FilterClause":
+        from .query import FilterClause
+
+        return FilterClause
+    if name == "JoinClause":
+        from .query import JoinClause
+
+        return JoinClause
+    if name == "SqlResourceGeneratorProvider":
+        from .providers import SqlResourceGeneratorProvider
+
+        return SqlResourceGeneratorProvider
+    raise AttributeError(name)

muscles_sql/cli.py

@@ -0,0 +1,144 @@
+import json
+from pathlib import Path
+
+import click
+
+from .config import DatabaseConfig
+from .connections import SqlConnectionRegistry, load_connection_registry
+from .providers import SqlGenerationRequest, SqlResourceGeneratorProvider
+
+
+@click.group()
+def main():
+    pass
+
+
+def _registry_from_options(url: str | None, config_path: str | None) -> SqlConnectionRegistry:
+    if config_path:
+        return load_connection_registry(config_path)
+    if url:
+        return SqlConnectionRegistry.from_database_config(DatabaseConfig(url=url))
+    raise click.UsageError("Use --url or --config.")
+
+
+@main.command("doctor")
+@click.option("--url", required=False)
+@click.option("--config", "config_path", type=click.Path(exists=True, dir_okay=False), required=False)
+@click.option("--connection", default="default", show_default=True)
+@click.option("--all", "all_connections", is_flag=True, default=False)
+def doctor(url: str | None, config_path: str | None, connection: str, all_connections: bool):
+    registry = _registry_from_options(url, config_path)
+    report = registry.inspect_all() if all_connections else registry.inspect(connection)
+    click.echo(json.dumps(report, ensure_ascii=False))
+
+
+@main.command("inspect")
+@click.option("--url", required=False)
+@click.option("--config", "config_path", type=click.Path(exists=True, dir_okay=False), required=False)
+@click.option("--connection", default="default", show_default=True)
+def inspect_cmd(url: str | None, config_path: str | None, connection: str):
+    registry = _registry_from_options(url, config_path)
+    click.echo(json.dumps(registry.inspect(connection), ensure_ascii=False))
+
+
+@main.group("migrate")
+def migrate():
+    pass
+
+
+@migrate.command("init")
+@click.option("--dir", "target_dir", default="migrations")
+def migrate_init(target_dir: str):
+    from .migrations import init_migrations
+
+    root = init_migrations(target_dir=target_dir)
+    click.echo(str(root))
+
+
+@migrate.command("revision")
+@click.option("--dir", "target_dir", default="migrations")
+@click.option("--message", default="revision")
+@click.option("--autogenerate", is_flag=True, default=False)
+@click.option("--url", default=None)
+def migrate_revision(target_dir: str, message: str, autogenerate: bool, url: str | None):
+    from .migrations import revision
+
+    revision(message=message, target_dir=target_dir, autogenerate=autogenerate, url=url)
+    click.echo("ok")
+
+
+@migrate.command("upgrade")
+@click.option("--dir", "target_dir", default="migrations")
+@click.option("--rev", default="head")
+@click.option("--url", default=None)
+def migrate_upgrade(target_dir: str, rev: str, url: str | None):
+    from .migrations import upgrade
+
+    upgrade(rev=rev, target_dir=target_dir, url=url)
+    click.echo("ok")
+
+
+@migrate.command("downgrade")
+@click.option("--dir", "target_dir", default="migrations")
+@click.option("--rev", default="-1")
+@click.option("--url", default=None)
+def migrate_downgrade(target_dir: str, rev: str, url: str | None):
+    from .migrations import downgrade
+
+    downgrade(rev=rev, target_dir=target_dir, url=url)
+    click.echo("ok")
+
+
+@migrate.command("history")
+@click.option("--dir", "target_dir", default="migrations")
+@click.option("--url", default=None)
+def migrate_history(target_dir: str, url: str | None):
+    from .migrations import history
+
+    history(target_dir=target_dir, url=url)
+    click.echo("ok")
+
+
+@migrate.command("current")
+@click.option("--dir", "target_dir", default="migrations")
+@click.option("--url", default=None)
+def migrate_current(target_dir: str, url: str | None):
+    from .migrations import current
+
+    current(target_dir=target_dir, url=url)
+    click.echo("ok")
+
+
+@main.group("generate")
+def generate():
+    pass
+
+
+@generate.command("resource")
+@click.argument("name")
+@click.option("--sql", is_flag=True, default=False)
+def generate_resource(name: str, sql: bool):
+    if sql:
+        provider = SqlResourceGeneratorProvider()
+        generated = provider.generate(
+            project_root=Path.cwd(),
+            request=SqlGenerationRequest(
+                generator_type="sql-resource",
+                name=name,
+                force=False,
+                with_tests=False,
+            ),
+        )
+        click.echo(generated[0])
+        return
+
+    root = Path("generated")
+    root.mkdir(exist_ok=True)
+    target = root / f"{name}.py"
+    content = f"class {name.title().replace('_', '')}Resource:\n    sql_enabled = {sql}\n"
+    target.write_text(content, encoding="utf-8")
+    click.echo(str(target))
+
+
+if __name__ == "__main__":
+    main()

muscles_sql/config.py

@@ -0,0 +1,46 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class DatabaseConfig:
+    url: str
+    echo: bool = False
+    pool_size: int = 5
+    max_overflow: int = 10
+    future: bool = True
+
+
+@dataclass(slots=True)
+class SqlConnectionConfig:
+    name: str
+    url: str
+    echo: bool = False
+    pool_size: int = 5
+    max_overflow: int = 10
+    future: bool = True
+    role: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def safe_url(self) -> str:
+        from sqlalchemy.engine import make_url
+
+        return make_url(self.url).render_as_string(hide_password=True)
+
+    def to_database_config(self) -> DatabaseConfig:
+        return DatabaseConfig(
+            url=self.url,
+            echo=self.echo,
+            pool_size=self.pool_size,
+            max_overflow=self.max_overflow,
+            future=self.future,
+        )
+
+    def to_contract(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "url": self.safe_url,
+            "role": self.role,
+            "metadata": dict(self.metadata),
+        }

muscles_sql/connections.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Iterable, Mapping
+
+from .config import DatabaseConfig, SqlConnectionConfig
+from .engine import EngineManager
+
+
+class UnknownSqlConnection(KeyError):
+    def __init__(self, name: str):
+        super().__init__(f"Unknown SQL connection: {name}")
+        self.name = name
+
+
+class SqlConnectionRegistry:
+    def __init__(self, configs: Iterable[SqlConnectionConfig] | None = None):
+        self._configs: dict[str, SqlConnectionConfig] = {}
+        self._managers: dict[str, EngineManager] = {}
+        for config in configs or ():
+            self.register(config)
+
+    @classmethod
+    def from_database_config(cls, config: DatabaseConfig, *, name: str = "default") -> "SqlConnectionRegistry":
+        return cls(
+            [
+                SqlConnectionConfig(
+                    name=name,
+                    url=config.url,
+                    echo=config.echo,
+                    pool_size=config.pool_size,
+                    max_overflow=config.max_overflow,
+                    future=config.future,
+                )
+            ]
+        )
+
+    def register(self, config: SqlConnectionConfig) -> None:
+        self._configs[config.name] = config
+        self._managers.pop(config.name, None)
+
+    def names(self) -> list[str]:
+        return sorted(self._configs)
+
+    def config(self, name: str = "default") -> SqlConnectionConfig:
+        try:
+            return self._configs[name]
+        except KeyError as exc:
+            raise UnknownSqlConnection(name) from exc
+
+    def manager(self, name: str = "default") -> EngineManager:
+        if name not in self._managers:
+            self._managers[name] = EngineManager(self.config(name).to_database_config())
+        return self._managers[name]
+
+    def session_factory(self, name: str = "default"):
+        return self.manager(name).session_factory
+
+    def session(self, name: str = "default"):
+        return self.manager(name).session()
+
+    def inspect(self, name: str = "default") -> dict[str, Any]:
+        from .inspect import inspect_sql_layer
+
+        config = self.config(name)
+        report = inspect_sql_layer(self.manager(name))
+        report["connection"] = config.to_contract()
+        return report
+
+    def inspect_all(self) -> dict[str, Any]:
+        reports = {name: self.inspect(name) for name in self.names()}
+        status = "ok" if all(report.get("status") == "ok" for report in reports.values()) else "error"
+        return {"status": status, "connections": reports}
+
+
+def connection_config_from_mapping(name: str, payload: str | Mapping[str, Any]) -> SqlConnectionConfig:
+    if isinstance(payload, str):
+        return SqlConnectionConfig(name=name, url=payload)
+    return SqlConnectionConfig(
+        name=str(payload.get("name", name)),
+        url=str(payload["url"]),
+        echo=bool(payload.get("echo", False)),
+        pool_size=int(payload.get("pool_size", 5)),
+        max_overflow=int(payload.get("max_overflow", 10)),
+        future=bool(payload.get("future", True)),
+        role=payload.get("role"),
+        metadata=dict(payload.get("metadata") or {}),
+    )
+
+
+def connection_registry_from_mapping(payload: Mapping[str, Any]) -> SqlConnectionRegistry:
+    raw_connections = payload.get("connections", payload)
+    if not isinstance(raw_connections, Mapping):
+        raise ValueError("SQL connection config must contain a mapping of connections.")
+    configs = [connection_config_from_mapping(str(name), value) for name, value in raw_connections.items()]
+    return SqlConnectionRegistry(configs)
+
+
+def load_connection_registry(path: str | Path) -> SqlConnectionRegistry:
+    import json
+
+    payload = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(payload, Mapping):
+        raise ValueError("SQL connection config must be a JSON object.")
+    return connection_registry_from_mapping(payload)

muscles_sql/engine.py

@@ -0,0 +1,19 @@
+from typing import Any
+
+from .config import DatabaseConfig
+
+
+class EngineManager:
+    def __init__(self, config: DatabaseConfig):
+        from sqlalchemy import create_engine
+        from sqlalchemy.orm import sessionmaker
+
+        kwargs: dict[str, Any] = {"echo": config.echo, "future": config.future}
+        if not config.url.startswith("sqlite"):
+            kwargs["pool_size"] = config.pool_size
+            kwargs["max_overflow"] = config.max_overflow
+        self.engine = create_engine(config.url, **kwargs)
+        self.session_factory = sessionmaker(bind=self.engine, autoflush=False, autocommit=False, future=True)
+
+    def session(self):
+        return self.session_factory()

muscles_sql/inspect.py

@@ -0,0 +1,26 @@
+def inspect_sql_layer(engine_manager) -> dict:
+    from time import perf_counter
+    from sqlalchemy import inspect, text
+
+    started = perf_counter()
+    with engine_manager.engine.connect() as conn:
+        conn.execute(text("SELECT 1"))
+    latency_ms = round((perf_counter() - started) * 1000, 3)
+    inspector = inspect(engine_manager.engine)
+    tables = []
+    for table_name in inspector.get_table_names():
+        tables.append(
+            {
+                "name": table_name,
+                "columns": [column["name"] for column in inspector.get_columns(table_name)],
+                "indexes": [index["name"] for index in inspector.get_indexes(table_name)],
+                "pk": inspector.get_pk_constraint(table_name).get("constrained_columns", []),
+            }
+        )
+    return {
+        "status": "ok",
+        "dialect": engine_manager.engine.dialect.name,
+        "driver": engine_manager.engine.dialect.driver,
+        "latency_ms": latency_ms,
+        "tables": tables,
+    }

muscles_sql/mapping.py

@@ -0,0 +1,71 @@
+from typing import Any
+
+TYPE_MAP: dict[str, str] = {
+    "String": "String",
+    "Text": "Text",
+    "Integer": "Integer",
+    "Numeric": "Numeric",
+    "Float": "Float",
+    "Boolean": "Boolean",
+    "Date": "Date",
+    "DateTime": "DateTime",
+}
+
+
+def _sa():
+    from sqlalchemy import Boolean, Column, Date, DateTime, Float, Integer, MetaData, Numeric, String, Table, Text
+
+    return {
+        "Boolean": Boolean,
+        "Column": Column,
+        "Date": Date,
+        "DateTime": DateTime,
+        "Float": Float,
+        "Integer": Integer,
+        "MetaData": MetaData,
+        "Numeric": Numeric,
+        "String": String,
+        "Table": Table,
+        "Text": Text,
+    }
+
+
+def _resolve_type(column_type: Any):
+    sa = _sa()
+    if isinstance(column_type, type):
+        name = column_type.__name__
+    else:
+        name = getattr(column_type, "__class__", type(column_type)).__name__
+    return sa.get(TYPE_MAP.get(name, "String"), sa["String"])
+
+
+def map_model(model_cls: type, table_name: str | None = None):
+    sa = _sa()
+    metadata = sa["MetaData"]()
+    columns = []
+    for field_name, field_def in model_cls.__dict__.items():
+        if field_name.startswith("_"):
+            continue
+        field_type = getattr(field_def, "field_type", None)
+        if field_type is None:
+            continue
+        sql_type = _resolve_type(field_type)
+        is_pk = bool(getattr(field_def, "primary_key", False))
+        nullable = bool(getattr(field_def, "nullable", not is_pk))
+        autoincrement = bool(
+            getattr(field_def, "autoincrement", False)
+            or (is_pk and sql_type is sa["Integer"])
+        )
+        columns.append(
+            sa["Column"](
+                field_name,
+                sql_type,
+                primary_key=is_pk,
+                nullable=nullable,
+                autoincrement=autoincrement,
+            )
+        )
+
+    if not columns:
+        raise ValueError(f"No mappable columns found in model {model_cls.__name__}")
+    return sa["Table"](table_name or model_cls.__name__.lower(), metadata, *columns, extend_existing=True)

muscles_sql/migrations.py

@@ -0,0 +1,132 @@
+from pathlib import Path
+import os
+from typing import Any
+
+
+def init_migrations(target_dir: str = "migrations") -> Path:
+    root = Path(target_dir)
+    versions = root / "versions"
+    root.mkdir(parents=True, exist_ok=True)
+    versions.mkdir(parents=True, exist_ok=True)
+    _ensure_bootstrap_files(root)
+    return root
+
+
+def _ensure_bootstrap_files(root: Path) -> None:
+    root.mkdir(parents=True, exist_ok=True)
+    env_py = root / "env.py"
+    script_mako = root / "script.py.mako"
+    readme = root / "README"
+    if not env_py.exists():
+        env_py.write_text(
+            "from __future__ import annotations\n"
+            "from alembic import context\n"
+            "from sqlalchemy import engine_from_config, pool\n\n"
+            "config = context.config\n"
+            "target_metadata = config.attributes.get('target_metadata')\n\n"
+            "def run_migrations_offline():\n"
+            "    url = config.get_main_option('sqlalchemy.url')\n"
+            "    context.configure(url=url, target_metadata=target_metadata, literal_binds=True)\n"
+            "    with context.begin_transaction():\n"
+            "        context.run_migrations()\n\n"
+            "def run_migrations_online():\n"
+            "    connectable = engine_from_config(config.get_section(config.config_ini_section) or {}, prefix='sqlalchemy.', poolclass=pool.NullPool)\n"
+            "    with connectable.connect() as connection:\n"
+            "        context.configure(connection=connection, target_metadata=target_metadata)\n"
+            "        with context.begin_transaction():\n"
+            "            context.run_migrations()\n\n"
+            "if context.is_offline_mode():\n"
+            "    run_migrations_offline()\n"
+            "else:\n"
+            "    run_migrations_online()\n",
+            encoding="utf-8",
+        )
+    if not script_mako.exists():
+        script_mako.write_text(
+            "\"\"\"${message}\n\n"
+            "Revision ID: ${up_revision}\n"
+            "Revises: ${down_revision | comma,n}\n"
+            "Create Date: ${create_date}\n"
+            "\"\"\"\n\n"
+            "from alembic import op\n"
+            "import sqlalchemy as sa\n\n"
+            "revision = ${repr(up_revision)}\n"
+            "down_revision = ${repr(down_revision)}\n"
+            "branch_labels = ${repr(branch_labels)}\n"
+            "depends_on = ${repr(depends_on)}\n\n"
+            "def upgrade():\n"
+            "    pass\n\n"
+            "def downgrade():\n"
+            "    pass\n",
+            encoding="utf-8",
+        )
+    if not readme.exists():
+        readme.write_text("Muscles SQL Alembic migration environment.\n", encoding="utf-8")
+
+
+def _load_alembic():
+    try:
+        from alembic import command
+        from alembic.config import Config
+    except Exception as exc:
+        raise RuntimeError("Alembic is required for migration commands") from exc
+    return command, Config
+
+
+def _resolve_url(url: str | None = None) -> str | None:
+    if url:
+        return url
+    env_url = os.getenv("MUSCLES_SQL_URL")
+    if env_url:
+        return env_url
+    return None
+
+
+def _config(target_dir: str = "migrations", url: str | None = None, target_metadata: Any | None = None):
+    _, Config = _load_alembic()
+    root = Path(target_dir)
+    _ensure_bootstrap_files(root)
+    cfg = Config()
+    cfg.set_main_option("script_location", target_dir)
+    resolved_url = _resolve_url(url)
+    if not resolved_url:
+        raise ValueError("Database URL is required for migration commands")
+    cfg.set_main_option("sqlalchemy.url", resolved_url)
+    if target_metadata is not None:
+        cfg.attributes["target_metadata"] = target_metadata
+    return cfg
+
+
+def revision(
+    message: str,
+    target_dir: str = "migrations",
+    autogenerate: bool = False,
+    url: str | None = None,
+    target_metadata: Any | None = None,
+) -> None:
+    command, _ = _load_alembic()
+    command.revision(
+        _config(target_dir, url=url, target_metadata=target_metadata),
+        message=message,
+        autogenerate=autogenerate,
+    )
+
+
+def upgrade(rev: str = "head", target_dir: str = "migrations", url: str | None = None) -> None:
+    command, _ = _load_alembic()
+    command.upgrade(_config(target_dir, url=url), rev)
+
+
+def downgrade(rev: str = "-1", target_dir: str = "migrations", url: str | None = None) -> None:
+    command, _ = _load_alembic()
+    command.downgrade(_config(target_dir, url=url), rev)
+
+
+def history(target_dir: str = "migrations", url: str | None = None) -> None:
+    command, _ = _load_alembic()
+    command.history(_config(target_dir, url=url))
+
+
+def current(target_dir: str = "migrations", url: str | None = None) -> None:
+    command, _ = _load_alembic()
+    command.current(_config(target_dir, url=url))

muscles_sql/providers.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class SqlGenerationRequest:
+    generator_type: str
+    name: str
+    force: bool = False
+    with_tests: bool = False
+
+
+class SqlResourceGeneratorProvider:
+    name = "muscles-sql.resource"
+
+    def supports(self, generator_type: str) -> bool:
+        return generator_type in {"sql-resource", "resource-sql"}
+
+    def generate(self, project_root: Path, request: SqlGenerationRequest) -> list[str]:
+        root = project_root / "generated"
+        root.mkdir(exist_ok=True)
+        target = root / f"{request.name}.py"
+        content = (
+            f"class {request.name.title().replace('_', '')}Resource:\n"
+            f"    sql_enabled = True\n"
+        )
+        target.write_text(content, encoding="utf-8")
+        return [str(target)]

muscles_sql/query.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class FilterClause:
+    field: str
+    op: str
+    value: Any = None
+
+
+@dataclass(frozen=True)
+class JoinClause:
+    table: Any
+    on: Any
+    is_outer: bool = False
+
+
+@dataclass(frozen=True)
+class QuerySpec:
+    filters: list[FilterClause] = field(default_factory=list)
+    or_filters: list[FilterClause] = field(default_factory=list)
+    joins: list[JoinClause] = field(default_factory=list)
+    select_columns: list[Any] = field(default_factory=list)
+    order_by: list[Any] = field(default_factory=list)
+    group_by: list[Any] = field(default_factory=list)
+    having: list[Any] = field(default_factory=list)
+    limit: int | None = 100
+    offset: int = 0
+    distinct: bool = False
+

muscles_sql/repository.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .query import FilterClause, JoinClause, QuerySpec
+
+
+class SqlRepository:
+    def __init__(self, session, table):
+        self.session = session
+        self.table = table
+
+    def create(self, data: dict):
+        from sqlalchemy import insert
+
+        result = self.session.execute(insert(self.table).values(**data))
+        return result.inserted_primary_key
+
+    def get(self, pk):
+        from sqlalchemy import select
+
+        pk_col = list(self.table.primary_key.columns)[0]
+        stmt = select(self.table).where(pk_col == pk)
+        return self.session.execute(stmt).mappings().first()
+
+    def list(self, limit: int = 100, offset: int = 0, order_by: Any = None):
+        from sqlalchemy import select
+
+        stmt = select(self.table).limit(limit).offset(offset)
+        if order_by is not None:
+            stmt = stmt.order_by(order_by)
+        return self.session.execute(stmt).mappings().all()
+
+    def find(self, filters: dict | None = None, limit: int = 100, offset: int = 0, order_by: Any = None):
+        from sqlalchemy import select
+
+        clauses = [FilterClause(field=field, op="eq", value=value) for field, value in (filters or {}).items()]
+        spec = QuerySpec(filters=clauses, limit=limit, offset=offset, order_by=[order_by] if order_by is not None else [])
+        stmt = self._build_select(spec)
+        return self.session.execute(stmt).mappings().all()
+
+    def count(self, filters: dict | None = None) -> int:
+        from sqlalchemy import func, select
+
+        stmt = select(func.count()).select_from(self.table)
+        filters = filters or {}
+        for field, value in filters.items():
+            stmt = stmt.where(getattr(self.table.c, field) == value)
+        return int(self.session.execute(stmt).scalar_one())
+
+    def exists(self, filters: dict) -> bool:
+        return self.count(filters) > 0
+
+    def update(self, pk, data: dict):
+        from sqlalchemy import update
+
+        pk_col = list(self.table.primary_key.columns)[0]
+        stmt = update(self.table).where(pk_col == pk).values(**data)
+        return self.session.execute(stmt).rowcount
+
+    def delete(self, pk):
+        from sqlalchemy import delete
+
+        pk_col = list(self.table.primary_key.columns)[0]
+        stmt = delete(self.table).where(pk_col == pk)
+        return self.session.execute(stmt).rowcount
+
+    def query(self, spec: QuerySpec):
+        stmt = self._build_select(spec)
+        return self.session.execute(stmt).mappings().all()
+
+    def first(self, spec: QuerySpec):
+        first_spec = QuerySpec(
+            filters=list(spec.filters),
+            or_filters=list(spec.or_filters),
+            joins=list(spec.joins),
+            select_columns=list(spec.select_columns),
+            order_by=list(spec.order_by),
+            group_by=list(spec.group_by),
+            having=list(spec.having),
+            limit=1,
+            offset=spec.offset,
+            distinct=spec.distinct,
+        )
+        stmt = self._build_select(first_spec)
+        return self.session.execute(stmt).mappings().first()
+
+    def scalar(self, spec: QuerySpec):
+        stmt = self._build_select(spec)
+        return self.session.execute(stmt).scalar()
+
+    def aggregate(self, spec: QuerySpec):
+        stmt = self._build_select(spec)
+        return self.session.execute(stmt).mappings().all()
+
+    def bulk_create(self, rows: list[dict]) -> int:
+        from sqlalchemy import insert
+
+        if not rows:
+            return 0
+        self.session.execute(insert(self.table), rows)
+        return len(rows)
+
+    def bulk_update(self, pk_field: str, rows: list[dict]) -> int:
+        if not rows:
+            return 0
+        updated = 0
+        for row in rows:
+            pk = row.get(pk_field)
+            if pk is None:
+                continue
+            data = {k: v for k, v in row.items() if k != pk_field}
+            if not data:
+                continue
+            updated += int(self.update(pk, data) or 0)
+        return updated
+
+    def upsert(self, row: dict, conflict_fields: list[str]):
+        from sqlalchemy import inspect
+        from sqlalchemy.dialects.sqlite import insert as sqlite_insert
+        from sqlalchemy.exc import OperationalError
+
+        if not self._has_unique_conflict_constraint(conflict_fields):
+            raise ValueError(
+                "conflict_fields must match a PRIMARY KEY or UNIQUE constraint for safe upsert fallback"
+            )
+
+        dialect_name = inspect(self.session.bind).dialect.name
+        if dialect_name == "sqlite":
+            stmt = sqlite_insert(self.table).values(**row)
+            update_data = {k: v for k, v in row.items() if k not in conflict_fields}
+            stmt = stmt.on_conflict_do_update(index_elements=conflict_fields, set_=update_data)
+            try:
+                self.session.execute(stmt)
+                return 1
+            except OperationalError:
+                # Fallback for tables where conflict_fields are not backed by unique/pk constraints.
+                pass
+
+        filters = {field: row[field] for field in conflict_fields if field in row}
+        if filters:
+            existing = self.find(filters=filters, limit=1)
+            if existing:
+                pk_col = list(self.table.primary_key.columns)[0].name
+                pk_val = existing[0][pk_col]
+                return self.update(pk_val, {k: v for k, v in row.items() if k != pk_col})
+
+        pk_col = list(self.table.primary_key.columns)[0].name
+        pk_val = row.get(pk_col)
+        if pk_val is not None and self.get(pk_val):
+            return self.update(pk_val, {k: v for k, v in row.items() if k != pk_col})
+        self.create(row)
+        return 1
+
+    def _has_unique_conflict_constraint(self, conflict_fields: list[str]) -> bool:
+        if not conflict_fields:
+            return False
+        conflict_set = set(conflict_fields)
+        pk_cols = {column.name for column in self.table.primary_key.columns}
+        if conflict_set == pk_cols:
+            return True
+
+        for constraint in getattr(self.table, "constraints", []):
+            columns = getattr(constraint, "columns", None)
+            if columns is None:
+                continue
+            if getattr(constraint, "unique", False) and {column.name for column in columns} == conflict_set:
+                return True
+
+        for index in getattr(self.table, "indexes", []):
+            if getattr(index, "unique", False) and {column.name for column in index.columns} == conflict_set:
+                return True
+
+        return False
+
+    def _build_select(self, spec: QuerySpec):
+        from sqlalchemy import and_, or_, select
+
+        columns = spec.select_columns or [self.table]
+        stmt = select(*columns)
+        if spec.distinct:
+            stmt = stmt.distinct()
+
+        for join in spec.joins:
+            if join.is_outer:
+                stmt = stmt.outerjoin(join.table, join.on)
+            else:
+                stmt = stmt.join(join.table, join.on)
+
+        if spec.filters:
+            stmt = stmt.where(and_(*[self._build_filter_expr(clause) for clause in spec.filters]))
+        if spec.or_filters:
+            stmt = stmt.where(or_(*[self._build_filter_expr(clause) for clause in spec.or_filters]))
+        if spec.group_by:
+            stmt = stmt.group_by(*spec.group_by)
+        if spec.having:
+            stmt = stmt.having(*spec.having)
+        if spec.order_by:
+            stmt = stmt.order_by(*spec.order_by)
+        if spec.limit is not None:
+            stmt = stmt.limit(spec.limit)
+        if spec.offset:
+            stmt = stmt.offset(spec.offset)
+        return stmt
+
+    def _build_filter_expr(self, clause: FilterClause):
+        column = getattr(self.table.c, clause.field)
+        op = clause.op.lower()
+        if op == "eq":
+            return column == clause.value
+        if op == "ne":
+            return column != clause.value
+        if op == "gt":
+            return column > clause.value
+        if op == "gte":
+            return column >= clause.value
+        if op == "lt":
+            return column < clause.value
+        if op == "lte":
+            return column <= clause.value
+        if op == "in":
+            return column.in_(clause.value or [])
+        if op == "like":
+            return column.like(clause.value)
+        if op == "is_null":
+            return column.is_(None) if clause.value else column.is_not(None)
+        raise ValueError(f"Unsupported filter operator: {clause.op}")

muscles_sql/uow.py

@@ -0,0 +1,47 @@
+from typing import Any
+
+
+class UnitOfWork:
+    def __init__(self, session_factory, *, isolation_level: str | None = None):
+        self._session_factory = session_factory
+        self._isolation_level = isolation_level
+        self.session: Any | None = None
+
+    def _require_session(self):
+        if self.session is None:
+            raise RuntimeError("UnitOfWork requires an active session; use it as a context manager first.")
+        return self.session
+
+    def __enter__(self):
+        session = self._session_factory()
+        if self._isolation_level:
+            session.connection(execution_options={"isolation_level": self._isolation_level})
+        self.session = session
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        session = self._require_session()
+        if exc_type is None:
+            session.commit()
+        else:
+            session.rollback()
+        session.close()
+        self.session = None
+
+    def begin_nested(self):
+        return self._require_session().begin_nested()
+
+    def with_retry(self, fn, *, max_attempts: int = 3, retry_on: tuple[type[Exception], ...] = ()):
+        if max_attempts < 1:
+            raise ValueError("max_attempts must be >= 1")
+        attempt = 0
+        while True:
+            attempt += 1
+            session = self._require_session()
+            try:
+                return fn(session)
+            except Exception as exc:
+                if retry_on and isinstance(exc, retry_on) and attempt < max_attempts:
+                    session.rollback()
+                    continue
+                raise

muscles_sql-1.0.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: muscles-sql
+Version: 1.0.0
+Summary: Muscles SQL data layer for repositories, migrations and AI-first workflow.
+Author-email: "Denis B." <denis@butko.info>
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: muscles<2.0.0,>=1.0.0rc1
+Requires-Dist: SQLAlchemy<3.0,>=2.0
+Requires-Dist: alembic<2.0,>=1.13
+Requires-Dist: click<9.0,>=8.1
+Requires-Dist: pydantic<3.0,>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
+
+# Muscles SQL
+
+Muscles SQL is a data layer package for SQL databases:
+- model-to-table mapping
+- engine and session management
+- repository CRUD and advanced query API (filters/operators/joins/aggregates)
+- transactions and Unit of Work (nested/savepoint/retry helpers)
+- migrations v2 commands (Alembic-compatible lazy-load)
+- inspect/doctor support with machine-readable diagnostics
+
+## Related Repositories
+
+- [`muscles`](https://github.com/butkoden/muscles) - core schemas, actions, DI and canonical documentation.
+- [`muscles-documents`](https://github.com/butkoden/muscles-documents) - document metadata/state can use SQL persistence in applications.
+- [`muscles-ai`](https://github.com/butkoden/muscles-ai) - AI/RAG flows can use SQL-backed application state without making SQL generic storage.
+- [`muscles-otel`](https://github.com/butkoden/muscles-otel) - observability hooks around SQL-backed flows.
+- [`muscles-benchmarks`](https://github.com/butkoden/muscles-benchmarks) - SQL transaction and mapping regression checks.
+
+## Quickstart
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install muscles-sql
+```
+
+For local development with the test dependencies:
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+muscles-sql doctor --url sqlite:///./app.db
+```
+
+## Named SQL Connections
+
+`muscles-sql` can manage multiple SQL connections without becoming a generic
+storage registry. The registry is SQL-only: it owns SQL connection configs,
+lazy SQLAlchemy `EngineManager` instances, sessions, inspect and doctor reports.
+
+```python
+from muscles_sql import SqlConnectionConfig, SqlConnectionRegistry
+
+registry = SqlConnectionRegistry(
+    [
+        SqlConnectionConfig(name="default", url="sqlite:///./app.db"),
+        SqlConnectionConfig(name="analytics", url="sqlite:///./analytics.db", role="read"),
+    ]
+)
+
+session = registry.session("analytics")
+report = registry.inspect("analytics")
+```
+
+CLI diagnostics can read a JSON config:
+
+```json
+{
+  "connections": {
+    "default": "sqlite:///./app.db",
+    "analytics": {"url": "sqlite:///./analytics.db", "role": "read"}
+  }
+}
+```
+
+```bash
+muscles-sql inspect --config sql-connections.json --connection analytics
+muscles-sql doctor --config sql-connections.json --all
+```
+
+Diagnostic output uses safe URLs and does not print passwords from DSNs.
+
+## Advanced Query Example
+
+```python
+from sqlalchemy import func
+from muscles_sql import FilterClause, JoinClause, QuerySpec, SqlRepository
+
+spec = QuerySpec(
+    filters=[FilterClause("status", "eq", "active")],
+    joins=[JoinClause(table=orders, on=users.c.id == orders.c.user_id)],
+    select_columns=[users.c.id, func.count(orders.c.id).label("orders_total")],
+    group_by=[users.c.id],
+    order_by=[users.c.id.asc()],
+)
+rows = SqlRepository(session, users).aggregate(spec)
+```

muscles_sql-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+muscles_sql/__init__.py,sha256=ykLLjAorsdniKIuCLvD7jXAPtIa1isN5Df5WgVzuhTw,2182
+muscles_sql/cli.py,sha256=aIHvZJ3ocxxxv1AejoiQC71ott5RcQfTvL-MQYAawno,4550
+muscles_sql/config.py,sha256=0z_GyprgaJxEHLuYSpqsuLtj2BO861_SuzEvmKD0pig,1125
+muscles_sql/connections.py,sha256=Q2VuBLimVWKjPNrrtQVg4JC_1Me3mCO-fwguWprvYsk,3921
+muscles_sql/engine.py,sha256=sA7LJOyYAOkwE9N5KEESmWiZ2pVwPZEjmBwLLgQFqN0,690
+muscles_sql/inspect.py,sha256=-o1vDXE4o72WEHhXd0uTQWov7LZ_wEbLLesjz41Sp6I,1005
+muscles_sql/mapping.py,sha256=N9UbtpD7LdP38pQ2jHlSx64uPuWWYA2uMWo0Bv6EAAE,2101
+muscles_sql/migrations.py,sha256=d7Kp9nB39R_bpTJ53rqrwXcx_BHjhN8C2dlObeoCjss,4757
+muscles_sql/providers.py,sha256=9IOIE-UK5ZlRo22n_YxhyTuxx9yryhK6cJUgQ0DkuBM,866
+muscles_sql/query.py,sha256=yroYWdq0OiwMdeZqfANPZtwK7u0pCvr6OX64QWmK_ts,817
+muscles_sql/repository.py,sha256=40oMelQG-dV9beAvm6jTEUnYRe28myRXQc5nKr_uovA,8512
+muscles_sql/uow.py,sha256=rVTZkwCkbG6HRSQaiEYTDel80tUkRRdhZPh6tlySGRc,1595
+muscles_sql-1.0.0.dist-info/METADATA,sha256=VjOhbxyx8TdAZ8LFZhbI6CDTiaFZ63H4nxCux-FqtRw,3311
+muscles_sql-1.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+muscles_sql-1.0.0.dist-info/entry_points.txt,sha256=-DFmYLPEOFdKfRd5LX6dNmPTtdjliQKUxeIBGiuRRFk,53
+muscles_sql-1.0.0.dist-info/top_level.txt,sha256=FqDIvlpbA1v3ly7oYMppc8psf_8Z2zeS2O9g--ZpGmk,12
+muscles_sql-1.0.0.dist-info/RECORD,,

muscles_sql-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

muscles_sql-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+muscles-sql = muscles_sql.cli:main

muscles_sql-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+muscles_sql