fix: make SQLAlchemy import lazy and declare it under [sink] extra

README.md

@@ -90,16 +90,22 @@ With the TUI:
 python -m pip install ".[tui]"
 ```
 
+With the SQLAlchemy sink integration:
+
+```bash
+python -m pip install ".[sink]"
+```
+
 With Redis support:
 
 ```bash
 python -m pip install ".[redis]"
 ```
 
-With both:
+With everything:
 
 ```bash
-python -m pip install ".[tui,redis]"
+python -m pip install ".[tui,sink,redis]"
 ```
 
 After install, the `adv` command is available in that environment.

adiuvare/integrations/flask.py

@@ -1,9 +1,9 @@
 import asyncio
 import json
 
+from .sqlalchemy import _sink_mode
 from werkzeug.wrappers import Request, Response
 
-from .sqlalchemy import _sink_mode
 from . import build_http_ctx, ctx_payload
 
 
@@ -13,7 +13,7 @@ def __init__(self, app, guard, flask_app=None) -> None:
         self._guard = guard
         self._flask = flask_app
 
-    def __call__(self, environ, start_response):
+    def __call__(self, environ, start_response): 
         req = Request(environ)
         raw_ip = req.headers.get("x-forwarded-for", "")
         ip = raw_ip.split(",", 1)[0].strip() or req.remote_addr or "127.0.0.1"

adiuvare/integrations/sqlalchemy.py

@@ -1,7 +1,5 @@
 from contextvars import ContextVar
 
-from sqlalchemy import event
-
 from ..signals.patterns import check_sql
 from ..vendor import detect_sqli, normalize
 
@@ -41,6 +39,9 @@ def check_statement(
 
 
 def attach_sink(engine, guard) -> None:
+
+    from sqlalchemy import event
+
     if getattr(engine, "_adiuvare_guard", None) is guard:
         return
 

docs/installation.md

@@ -12,6 +12,7 @@ Use these commands to install Adiuvare directly from GitHub into your environmen
 | --- | --- |
 | core library | `python -m pip install "git+https://github.com/0-Shimanshu/ADIUVARE.git"` |
 | core + TUI | `python -m pip install "adiuvare[tui] @ git+https://github.com/0-Shimanshu/ADIUVARE.git"` |
+| core + SQLAlchemy sink | `python -m pip install "adiuvare[sink] @ git+https://github.com/0-Shimanshu/ADIUVARE.git"` |
 | core + Redis | `python -m pip install "adiuvare[redis] @ git+https://github.com/0-Shimanshu/ADIUVARE.git"` |
 
 ### For Project Contributors (Local Repository Clone)
@@ -22,7 +23,7 @@ If you are a developer working directly inside a local clone of the repository s
 | --- | --- |
 | editable local dev | `python -m pip install -e .` |
 | editable dev test stack | `python -m pip install -e ".[dev]"` |
-| editable dev with extras | `python -m pip install -e ".[dev,tui,redis]"` |
+| editable dev with extras | `python -m pip install -e ".[dev,tui,sink,redis]"` |
 
 ## Verify the install
 
@@ -76,6 +77,27 @@ The current TUI has seven screens:
 - Audit
 - Changes
 
+## Sink install
+
+If you want to use the SQLAlchemy sink integration (`attach_sink()`), install
+the sink extra.
+
+```bash
+python -m pip install "adiuvare[sink] @ git+https://github.com/0-Shimanshu/ADIUVARE.git"
+```
+
+For local development:
+
+```bash
+pip install -e ".[sink]"
+```
+
+Once Adiuvare is published to PyPI, the shorter form will work:
+
+```bash
+pip install "adiuvare[sink]"
+```
+
 ## Redis install
 
 If you want the Redis event-stream backend, install the Redis extra.
@@ -143,6 +165,14 @@ heuristics. That keeps the runtime usable, but it is still the weaker path.
 
 ## Troubleshooting
 
+### `SQLAlchemy is required to use attach_sink()`
+
+Install the sink extra:
+
+```bash
+pip install "adiuvare[sink] @ git+https://github.com/0-Shimanshu/ADIUVARE.git"
+```
+
 ### `tui deps are missing`
 
 Install the TUI extra:

docs/integrations/django.md

@@ -7,6 +7,24 @@ and direct block or throttle outcomes.
 Use the explicit Django attach path here. `Guard.auto(...)` is not the right
 shortcut for Django at the moment.
 
+## Sink install
+
+If you want to use the SQLAlchemy sink integration alongside Django, install
+the `sink` extra:
+
+```bash
+# from GitHub (before PyPI publish)
+pip install "adiuvare[sink] @ git+https://github.com/0-Shimanshu/ADIUVARE.git"
+
+# local development
+pip install -e ".[sink]"
+
+# once published to PyPI
+pip install "adiuvare[sink]"
+```
+
+See [SQLAlchemy sink](../integrations/sqlalchemy.md) for usage.
+
 ## Working example
 
 A maintained Django demo is available here:

docs/integrations/sqlalchemy.md

@@ -4,6 +4,22 @@ Adiuvare can inspect SQL statements close to the sink. This is not the main
 request middleware path. It is the extra layer that runs near real SQL
 execution when you want a last checkpoint there too.
 
+## Install
+
+The SQLAlchemy sink integration requires SQLAlchemy. Install it via the `sink`
+extra:
+
+```bash
+# from GitHub (before PyPI publish)
+pip install "adiuvare[sink] @ git+https://github.com/0-Shimanshu/ADIUVARE.git"
+
+# local development
+pip install -e ".[sink]"
+
+# once published to PyPI
+pip install "adiuvare[sink]"
+```
+
 ## Quick example
 
 ```python

docs/quickstart.md

@@ -18,6 +18,12 @@ If you also want the TUI:
 python -m pip install "adiuvare[tui] @ git+https://github.com/0-Shimanshu/ADIUVARE.git"
 ```
 
+If you want the SQLAlchemy sink integration:
+
+```bash
+python -m pip install "adiuvare[sink] @ git+https://github.com/0-Shimanshu/ADIUVARE.git"
+```
+
 If you want the Redis backend too:
 
 ```bash

pyproject.toml

@@ -14,6 +14,9 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+sink = [
+  "sqlalchemy",
+]
 dev = [
   "pytest",
   "pytest-asyncio",

tests/test_flask.py

@@ -179,6 +179,12 @@ def billing():
     assert res.status_code == 200
 
 
+def test_flask_middleware_import_does_not_require_sqlalchemy():
+
+    from adiuvare.integrations.flask import AdiuvareMiddleware
+    assert AdiuvareMiddleware is not None
+
+
 def _capture_flask_payload(monkeypatch, guard, client_call_func) -> str | None:
     captured = None
 

tests/test_sink.py

@@ -1,9 +1,10 @@
 import pytest
-import sqlalchemy as sa
 
-from adiuvare import Guard
-from adiuvare.integrations.django_sink import wrap_query
-from adiuvare.integrations.sqlalchemy import AdiuvareBlockError, _sink_mode, attach_sink, check_statement
+sa = pytest.importorskip("sqlalchemy", reason="sqlalchemy not installed, skipping sink tests")
+
+from adiuvare import Guard  # noqa: E402
+from adiuvare.integrations.django_sink import wrap_query  # noqa: E402
+from adiuvare.integrations.sqlalchemy import AdiuvareBlockError, _sink_mode, attach_sink, check_statement  # noqa: E402
 
 
 def test_sqlalchemy_sink_can_block_inline():