db-graphql-gateway 0.1.0__tar.gz

db_graphql_gateway-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run pre-commit
+        run: uv run pre-commit run --all-files
+
+      - name: Run tests
+        run: uv run pytest tests/ -v

db_graphql_gateway-0.1.0/.github/workflows/conformance.yml

@@ -0,0 +1,33 @@
+name: Conformance Tests
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  conformance:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        adapter: [postgres, mysql, sqlite]
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v2
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install Dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run Conformance Suite
+        run: uv run pytest tests/conformance/ -v -k "[${{ matrix.adapter }}]"

db_graphql_gateway-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: Deploy docs
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install MkDocs Material
+        run: pip install mkdocs-material
+
+      - name: Deploy Docs to GitHub Pages
+        run: mkdocs gh-deploy --force

db_graphql_gateway-0.1.0/.github/workflows/integration.yml

@@ -0,0 +1,30 @@
+name: Integration Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  integration-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run Integration Tests
+        run: |
+          ./integration_tests/run_all.sh

db_graphql_gateway-0.1.0/.gitignore

@@ -0,0 +1,57 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+.venv/
+env/
+.env/
+ENV/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+
+# Testing and Linting
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# MkDocs
+site*
+
+# Environment Variables
+.env
+
+# OS generated files
+.DS_Store
+Thumbs.db

db_graphql_gateway-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.4
+    hooks:
+      - id: ruff
+        args: [ --fix ]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        additional_dependencies: ["types-PyYAML", "strawberry-graphql", "PyJWT", "testcontainers"]

db_graphql_gateway-0.1.0/CONTRIBUTING_ADAPTER.md

@@ -0,0 +1,94 @@
+# Contributing a New Database Adapter
+
+Thank you for your interest in expanding the database support of `db-graphql-gateway`! Our goal is to maintain a truly database-agnostic GraphQL interface. This means that users should be able to swap adapters without modifying their GraphQL schemas, authorization policies, or application code.
+
+This guide explains the `DatabaseAdapter` protocol, how to build a new adapter, and how to prove it works using the **Cross-Adapter Conformance Suite**.
+
+## The `DatabaseAdapter` Protocol
+
+To integrate a new database engine (e.g., SQL Server, DuckDB, CockroachDB), you must implement the `DatabaseAdapter` interface (found in `src/db_graphql_gateway/database/adapters/interfaces.py`).
+
+The adapter acts as a bridge between the engine-agnostic core (`GraphQLSchemaBuilder`, `AuthorizationEngine`) and the underlying database dialect.
+
+### Key Components
+
+1. **`DatabaseAdapter`**: Manages the connection pool, executes queries, and returns raw data.
+2. **`SchemaInspector`**: Introspects the database to dynamically generate the canonical schema.
+3. **`TypeMapper`**: Translates dialect-specific types (e.g., MySQL's `TINYINT(1)`) into abstract GraphQL IR types (`GraphQLType.BOOLEAN`).
+4. **`QueryCompiler`**: Usually inherits from `BaseQueryCompiler` and overrides dialect-specific AST-to-SQL logic.
+
+### Capability Flags
+
+When configuring your `QueryCompiler` or `Adapter`, you may need to define capability flags that instruct the core gateway on how to handle the dialect's quirks:
+
+- `supports_returning` (bool): Set to `True` if your engine supports `RETURNING` clauses (like Postgres). If `False` (like SQLite/MySQL), the gateway will automatically use a "SELECT-after-write" pattern.
+- `fetch_after_write` (bool): Flag emitted in the `MutationPlan` for engines lacking `RETURNING` to trigger the secondary select.
+- `placeholder_style` (enum/string): e.g., `?` for SQLite, `%s` for MySQL, `$1` for Postgres. Ensures parameterized queries match the underlying driver's expectations.
+
+## Building a New Adapter: Worked Example (SQLite)
+
+Let's look at how SQLite was implemented.
+
+### 1. Connection & Execution
+```python
+class SQLiteAdapter(DatabaseAdapter):
+    async def execute_query(self, query: str, params: list[Any]) -> list[dict[str, Any]]:
+        async with self.pool.acquire() as conn:
+            cursor = await conn.execute(query, params)
+            rows = await cursor.fetchall()
+            return [dict(row) for row in rows]
+```
+
+### 2. Query Compilation
+Inherit from `BaseQueryCompiler` to get 90% of ANSI SQL behavior for free.
+```python
+class SQLiteQueryCompiler(BaseQueryCompiler):
+    def __init__(self):
+        super().__init__()
+        self.placeholder = "?"
+        self.supports_returning = False
+```
+
+### 3. Engine Gotchas (Checklist)
+
+Before building, verify the following against your driver:
+- [ ] **Placeholder Style**: Does the driver use `?`, `%s`, `:name`, or `$1`?
+- [ ] **Identifier Quoting**: Does it use `""` (Postgres/SQLite) or `\`\`` (MySQL)? Override `quote_identifier()` in your compiler.
+- [ ] **Boolean Types**: Does the engine lack a native `BOOLEAN`? Ensure your `TypeMapper` intercepts it (e.g., `TINYINT(1) -> BOOLEAN`).
+- [ ] **Upsert Syntax**: Does it use `ON CONFLICT` or `ON DUPLICATE KEY UPDATE`?
+
+### Explicit Non-Goals
+The `DatabaseAdapter` protocol does **not** need to support highly proprietary, engine-specific extensions (e.g., Postgres PostGIS, Oracle XMLType) if there is no cross-engine equivalent. Expose these via adapter-level opt-in configuration, not by muddying the core protocol.
+
+## Passing the Conformance Suite
+
+Your PR **will not be merged** unless it passes the Conformance Suite. This suite runs identical GraphQL queries against all adapters to guarantee 100% behavioral parity (including pagination, relationships, and authorization pushdowns).
+
+### How to hook into the Conformance Suite:
+
+1. Open `tests/conformance/conftest.py`.
+2. Add your engine to the parameter matrix:
+   ```python
+   @pytest_asyncio.fixture(params=["sqlite", "mysql", "postgres", "your_engine"])
+   ```
+3. Update the `db_adapter` fixture to provision your engine (use `testcontainers` if it requires a daemon). The fixture must use the generic `get_ddl("your_engine")` string to instantiate the canonical schema:
+   ```python
+   elif engine == "your_engine":
+       # Setup your engine here
+       for stmt in get_ddl("your_engine"):
+           await conn.execute(stmt)
+   ```
+4. Run the suite: `uv run pytest tests/conformance/ -k "db_adapter[your_engine]"`
+
+If your compiler and type mapper are correct, all tests will pass without writing a single line of test code!
+
+## Entry Points & Packaging
+
+To keep the core package lightweight, third-party adapters should be published as separate packages (e.g., `db-graphql-gateway-duckdb`).
+
+Register your adapter in your `pyproject.toml` so the gateway can auto-discover it:
+```toml
+[project.entry-points."db_graphql_gateway.adapters"]
+duckdb = "my_duckdb_package.adapter:DuckDBAdapter"
+```
+Users will then configure the gateway with `engine="duckdb"` and the plugin system will handle the rest.

db_graphql_gateway-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Author
+
+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.

db_graphql_gateway-0.1.0/Makefile

@@ -0,0 +1,15 @@
+.PHONY: install lint typecheck test
+
+install:
+	uv venv
+	uv pip install -e ".[dev,postgres]"
+
+lint:
+	uv run ruff check src/ tests/
+	uv run ruff format --check src/ tests/
+
+typecheck:
+	uv run mypy src/ tests/
+
+test:
+	uv run pytest

db_graphql_gateway-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.5
+Name: db-graphql-gateway
+Version: 0.1.0
+Summary: Automatically generate a secure, production-ready GraphQL API from a database connection.
+Author-email: Mukesh M Lohar <mukesh1lohar@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyjwt[crypto]>=2.8.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: strawberry-graphql>=0.200.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: testcontainers[postgres]>=4.4.1; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.141.1; extra == 'fastapi'
+Requires-Dist: httpx>=0.28.1; extra == 'fastapi'
+Provides-Extra: mysql
+Requires-Dist: asyncmy>=0.2.14; extra == 'mysql'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.28.0; extra == 'postgres'
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.22.1; extra == 'sqlite'
+Description-Content-Type: text/markdown
+
+# db-graphql-gateway
+
+Automatically generate a secure, production-ready GraphQL API from a database connection. 
+
+## Features
+- **Schema Discovery:** Automatically inspects your database schema and generates corresponding GraphQL types.
+- **Relationships:** Resolves foreign keys to automatically wire up GraphQL associations.
+- **Pagination:** Built-in Relay-style cursor pagination.
+- **Authorization & Security:** Configurable JWT/OIDC support and query complexity/depth protection.
+- **Performance:** Built-in DataLoader support to protect against N+1 query problems.
+
+## Getting Started
+See documentation for full setup instructions.

db_graphql_gateway-0.1.0/README.md

@@ -0,0 +1,13 @@
+# db-graphql-gateway
+
+Automatically generate a secure, production-ready GraphQL API from a database connection. 
+
+## Features
+- **Schema Discovery:** Automatically inspects your database schema and generates corresponding GraphQL types.
+- **Relationships:** Resolves foreign keys to automatically wire up GraphQL associations.
+- **Pagination:** Built-in Relay-style cursor pagination.
+- **Authorization & Security:** Configurable JWT/OIDC support and query complexity/depth protection.
+- **Performance:** Built-in DataLoader support to protect against N+1 query problems.
+
+## Getting Started
+See documentation for full setup instructions.

db_graphql_gateway-0.1.0/STATE.md

@@ -0,0 +1,27 @@
+# STATE: db-graphql-gateway
+
+## Current Status
+- Phase 1 (Foundation) has been successfully completed.
+- Phase 2 (PostgreSQL Introspection) has been successfully completed.
+- Phase 3 (Schema IR) has been successfully completed.
+- Phase 4 (Basic GraphQL Generation) has been successfully completed.
+- Phase 5 (Filter, Sort, Pagination) has been successfully completed.
+- Phase 6 (Relationships & DataLoader) has been successfully completed.
+- Phase 7 (Query Planner) has been successfully completed.
+- Phase 8 (Authentication) has been successfully completed.
+- Phase 9 (Authorization) has been successfully completed.
+- Phase 10 (Security Hardening) has been successfully completed.
+- Phase 11 (Mutations) has been successfully completed.
+- Phase 12 (FastAPI/ORM Integrations) has been successfully completed.
+- Phase 13 (CLI Tooling) has been successfully completed.
+- [x] Phase 14 (Final Testing & Documentation) has been successfully completed.
+  - Developed end-to-end acceptance tests.
+  - Written extensive MkDocs documentation covering `ARCHITECTURE.md`, `SECURITY.md`, `BENCHMARKS.md`, and more.
+  - Successfully addressed strict typing with `pre-commit --all-files`.
+
+## Next Actions
+- Project is effectively complete! All functionality, tests, and documentation are verified.
+- Built a Docker-based integration test workflow with strict security and type checks, which runs 9 advanced test levels natively asserting against real postgres.
+
+## Issues / Blockers
+- None.

db_graphql_gateway-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,229 @@
+# Architecture: db-graphql-gateway
+
+The `db-graphql-gateway` is designed with a strict separation of concerns, decoupling the database
+inspection and query compilation from the GraphQL presentation layer and authentication logic.
+
+---
+
+## 1. Core Execution Pipeline
+
+The life cycle of a GraphQL query from the HTTP request down to the database engine follows this
+strict pipeline:
+
+```mermaid
+flowchart TB
+    classDef client fill:#e0f7fa,stroke:#006064,stroke-width:2px,color:#006064
+    classDef security fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#e65100
+    classDef core fill:#e8eaf6,stroke:#1a237e,stroke-width:2px,color:#1a237e
+    classDef db fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#1b5e20
+
+    Client([GraphQL Client]):::client -->|HTTP POST| Auth(Authentication Provider):::security
+
+    subgraph "GraphQL Gateway Pipeline"
+        Auth -->|Verified JWT| Context(Auth Context)
+        Context --> Resolver(Strawberry Resolver):::core
+        
+        subgraph "Execution & Planning"
+            Resolver --> Limits{AST Limits}:::security
+            Limits --> Planner(Query Planner):::core
+            Planner --> DataLoader(DataLoader Registry):::core
+        end
+
+        subgraph "Security & Database Abstraction"
+            DataLoader --> AuthZ(Authorization Engine):::security
+            AuthZ --> |Inject SQL Policies| AdapterProtocol[[DatabaseAdapter Protocol]]:::core
+        end
+    end
+
+    AdapterProtocol --> PG[(PostgreSQL)]:::db
+    AdapterProtocol --> SQ[(SQLite)]:::db
+    AdapterProtocol --> MY[(MySQL/MariaDB)]:::db
+```
+
+---
+
+## 2. Package Boundaries
+
+The codebase is strictly separated into four functional areas:
+
+<div class="grid cards" markdown>
+
+-   :material-database: **Database Abstraction**
+    ---
+    Located in `database/`. Handles adapters (`PostgresAdapter`, `SQLiteAdapter`,
+    `MySQLAdapter`), schema inspection, normalised models, and dialect-parameterised
+    query compilers. **No dialect-specific logic leaks above this layer.**
+
+-   :material-transit-connection-variant: **Schema Intermediate Representation**
+    ---
+    Located in `schema/ir/`. The source of truth mapping database structure to
+    GraphQL schemas. It is database-agnostic and GraphQL-agnostic.
+
+-   :material-graphql: **GraphQL Generation**
+    ---
+    Located in `graphql/`. Converts the IR into a Strawberry GraphQL schema (types,
+    queries, mutations) and handles execution, filtering, sorting, pagination.
+    Talks only to the IR and the `DatabaseAdapter` protocol — never to a dialect.
+
+-   :material-security: **Security & Auth**
+    ---
+    Located in `auth/` and `security/`. Validates callers (e.g., JWT), evaluates
+    contextual policies to generate SQL predicate trees (`FilterCondition` /
+    `FilterGroup`), and enforces query complexity budgets and AST limits. Produces
+    dialect-neutral predicate objects; placeholder style is owned by the compiler.
+
+</div>
+
+---
+
+## 3. Multi-Dialect Adapter Architecture
+
+### 3.1 `DatabaseAdapter` Protocol
+
+Every adapter implements the same protocol from `database/adapters/interfaces.py`:
+
+```python
+class DatabaseAdapter(Protocol):
+    # ── Dialect capability flags ──────────────────────────────────────────
+    supports_returning: bool          # RETURNING clause supported after DML
+    supports_upsert_on_conflict: bool # ON CONFLICT DO UPDATE / ON DUPLICATE KEY
+    placeholder_style: PlaceholderStyle  # "numbered" | "qmark" | "named"
+    identifier_quote_char: str        # '"' | '`' | '['
+
+    async def connect(self) -> None: ...
+    async def close(self) -> None: ...
+    async def execute(self, query: CompiledQuery) -> QueryResult: ...
+    async def execute_many(self, queries: list[CompiledQuery]) -> list[QueryResult]: ...
+    def inspector(self) -> SchemaInspector: ...
+    def compiler(self) -> QueryCompiler: ...
+    def type_mapper(self) -> TypeMapper: ...
+```
+
+### 3.2 `BaseQueryCompiler`
+
+All SELECT / DML SQL generation lives in `database/adapters/base_compiler.py`.
+Dialect subclasses only set three class-level attributes:
+
+| Subclass | `placeholder_style` | `identifier_quote_char` | `supports_returning` |
+|---|---|---|---|
+| `PostgresQueryCompiler` | `"numbered"` (`$1, $2, …`) | `"` | `True` |
+| `SQLiteQueryCompiler` | `"qmark"` (`?, ?, …`) | `"` | runtime-detected (≥ 3.35.0) |
+| `MySQLQueryCompiler` | `"qmark"` (`?, ?, …`) | `` ` `` | `False` |
+
+When `supports_returning = False`, `compile_mutation()` sets
+`CompiledQuery.fetch_after_write = True` and the adapter's `execute()` issues a
+follow-up `SELECT` using `cursor.lastrowid` (INSERT) or the known PK value
+(UPDATE / DELETE). This pattern is called **SELECT-after-write**.
+
+### 3.3 Introspection
+
+Each adapter ships its own `SchemaInspector` that reads dialect-specific metadata:
+
+| Adapter | Introspection source |
+|---|---|
+| `PostgresSchemaInspector` | `pg_class`, `pg_attribute`, `pg_constraint`, `pg_enum` |
+| `SQLiteSchemaInspector` | `PRAGMA table_info`, `PRAGMA foreign_key_list`, `sqlite_master` |
+| `MySQLSchemaInspector` | `information_schema.columns`, `information_schema.key_column_usage` |
+
+All three produce the **same** `DatabaseSchema → Table → Column` data model.
+`IRBuilder.build()` is called identically regardless of which inspector ran.
+
+---
+
+## 4. Schema Intermediate Representation (IR)
+
+The Gateway decouples the database schema from the GraphQL schema using the IR
+(`GraphQLTypeIR`, `GraphQLFieldIR`).
+
+1. **Introspection (`inspector.py`)**: Reads dialect-specific system catalogs to
+   construct a `DatabaseSchema` with normalised `Column.type` strings.
+2. **Type mapping (`TypeMapper`)**: Each adapter's `TypeMapper` converts
+   normalised column types to abstract GraphQL scalar names (`"Int"`, `"Float"`,
+   `"String"`, `"DateTime"`, `"Boolean"`, `"JSON"`). No raw DB type strings leak
+   past the `TypeMapper`.
+3. **IR Build (`IRBuilder`)**: Converts the low-level schema into GraphQL-centric
+   constructs. During this phase, `GatewayConfig` overrides are applied.
+   **Sensitive fields** (e.g., `password`, `token`) are automatically redacted here
+   based on name-pattern matching — dialect-agnostically.
+
+---
+
+## 5. GraphQL Schema Generation (Build-Time)
+
+The `GraphQLSchemaBuilder` transforms the IR into a Strawberry GraphQL schema
+dynamically using Python's `type` function. This happens exactly **once at startup**.
+
+### Dynamic Annotations & Mypy
+Because Strawberry relies heavily on Python's type hints (`__annotations__`) to
+build the static GraphQL schema, the Builder must dynamically construct these
+dictionaries for every resolver it generates.
+
+```python title="Injecting annotations dynamically to satisfy Strawberry"
+update_fn.__annotations__ = {
+    "info": Info,
+    "id": pk_type,
+    "input": update_input_type,
+    "expected_version": Optional[int],
+    "return": Optional[sb_type],
+}
+```
+
+!!! note "Strict Typing"
+    This architecture cleanly separates the dynamic runtime from static analysis,
+    allowing the core engine to pass strict `mypy` checks.
+
+---
+
+## 6. Execution & DataLoading (Per-Request)
+
+When a resolver executes, it does not use an ORM. It builds a `QueryPlan` that is
+compiled directly into SQL via the adapter's `QueryCompiler`.
+
+### N+1 Query Elimination
+Nested relationship fields use Strawberry DataLoaders that batch foreign keys at
+execution time. The query compiler merges these batched IDs (e.g.,
+`WHERE author_id IN ($1, $2)` or `WHERE author_id IN (?, ?)`) ensuring constant
+$O(1)$ database execution regardless of the depth of the graph.
+
+The `DataLoaderRegistry` receives a `schema_map` dict (`type_name → schema_name`)
+from `GraphQLSchemaBuilder`, so relationship batch queries use the correct schema
+name for each adapter (e.g., `"public"` for Postgres, `"main"` for SQLite).
+
+### Optimistic Concurrency & Soft Deletes
+The `IRBuilder` automatically detects `version` and `deleted_at` columns.
+
+- **Soft Deletes**: List queries automatically append `deleted_at IS NULL` filters,
+  and `delete_` mutations are converted into `update_` operations that set the
+  deletion timestamp.
+- **Optimistic Locking**: Mutations include an `expected_version` argument. If
+  provided, the update query asserts `version = <expected>` and increments it,
+  failing if another transaction modified the row concurrently.
+
+Both features are detected from **IR field names** (`f.name == "deleted_at"`,
+`f.name == "version"`) — never from raw schema or adapter code.
+
+---
+
+## 7. Authorization Predicates
+
+!!! danger "Zero Memory Filtering"
+    The Gateway **never** filters sensitive data in Python memory. All authorization
+    policies are pushed down to the database engine as SQL `WHERE` predicates,
+    regardless of which adapter is in use.
+
+The `AuthorizationEngine` evaluates contextual policies and generates
+`FilterCondition` / `FilterGroup` predicate trees. When the `QueryCompiler` builds
+the final SQL string, it merges the basic user `WHERE` filters with the
+authorization predicates.
+
+The placeholder style (e.g., `$1` for Postgres, `?` for SQLite/MySQL) is owned
+**exclusively by the compiler** — the auth engine produces dialect-neutral predicate
+objects and has no knowledge of the underlying database engine.
+
+For example, a policy defining `owner_id = $user_id` on the `tasks` table will
+statically inject:
+
+- `AND "owner_id" = $1` in Postgres SQL
+- `AND "owner_id" = ?` in SQLite / MySQL SQL
+
+In all cases, unauthorized rows are **never loaded into memory**.