pico-sqlalchemy 0.3.0__tar.gz → 0.5.0__tar.gz

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.5.0}/.github/dependabot.yml

@@ -4,7 +4,6 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
-
   - package-ecosystem: "pip"
     directory: "/"
     schedule:

pico_sqlalchemy-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,90 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install tox
+      - name: Run tests with coverage
+        env:
+          SETUPTOOLS_SCM_PRETEND_VERSION: "0.1.0"
+        run: |
+          tox -e cov
+          mv .coverage .coverage.${{ matrix.python-version }}
+      - uses: actions/upload-artifact@v7
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: .coverage.${{ matrix.python-version }}
+          include-hidden-files: true
+          if-no-files-found: error
+
+  coverage:
+    needs: tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - uses: actions/download-artifact@v8
+        with:
+          path: coverage-reports
+      - name: Combine and upload
+        run: |
+          pip install coverage
+          files=$(find coverage-reports -type f -name ".coverage.*")
+          if [ -z "$files" ]; then echo "No coverage files"; exit 1; fi
+          coverage combine $files
+          coverage xml
+      - uses: codecov/codecov-action@v7
+        continue-on-error: true
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+          fail_ci_if_error: false
+
+  sonar:
+    if: github.event_name == 'push'
+    needs: tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: SonarSource/sonarqube-scan-action@v6
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+        with:
+          args: >
+            -Dsonar.host.url=https://sonarcloud.io
+            -Dsonar.organization=dperezcabrera
+            -Dsonar.projectKey=dperezcabrera_${{ github.event.repository.name }}
+            -Dsonar.projectName=${{ github.event.repository.name }}
+            -Dsonar.sources=src
+            -Dsonar.tests=tests
+            -Dsonar.python.version=3.11,3.12,3.13,3.14

pico_sqlalchemy-0.5.0/.github/workflows/codeql.yml

@@ -0,0 +1,21 @@
+name: CodeQL
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1"
+
+permissions:
+  security-events: write
+  contents: read
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: github/codeql-action/init@v4
+        with: { languages: python }
+      - uses: github/codeql-action/analyze@v4

pico_sqlalchemy-0.5.0/.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: Docs
+on:
+  push:
+    branches: [main]
+    paths: [docs/**, mkdocs.yml]
+  pull_request:
+    branches: [main]
+    paths: [docs/**, mkdocs.yml]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-python@v6
+        with: { python-version: "3.12" }
+      - run: pip install -r docs/requirements.txt
+      - run: mkdocs build --strict
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v7
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-python@v6
+        with: { python-version: "3.12" }
+      - run: pip install -r docs/requirements.txt
+      - run: mkdocs build --strict --verbose
+      - uses: actions/upload-pages-artifact@v5
+        with: { path: site }
+      - id: deployment
+        uses: actions/deploy-pages@v5

pico_sqlalchemy-0.5.0/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-python@v6
+        with: { python-version: "3.x" }
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+          verify-metadata: true
+          attestations: true

pico_sqlalchemy-0.5.0/.sonarcloud.properties

@@ -0,0 +1,3 @@
+sonar.python.version=3.11,3.12,3.13,3.14
+sonar.sources=src
+sonar.tests=tests

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.5.0}/AGENTS.md

@@ -35,9 +35,10 @@ src/pico_sqlalchemy/
 - **Propagation modes**: REQUIRED, REQUIRES_NEW, MANDATORY, NEVER, NOT_SUPPORTED, SUPPORTS
 - **Priority chain**: `@transactional` > `@query` (read-only) > `@repository` (read-write)
 - **`SessionManager`**: Created by `SqlAlchemyFactory` (not `@component`). Manages engine, sessions, transactions
-- **`_tx_context` ContextVar**: Holds `TransactionContext` for session propagation. Separate from pico-ioc's "transaction" scope (which is for DI caching)
+- **`_tx_context` ContextVar**: Holds `TransactionContext` (the session) for propagation across nested calls — the *session* side of a transaction
+- **`"transaction"` DI scope**: `TransactionalInterceptor` activates pico-ioc's `"transaction"` scope (with `cleanup=True`) whenever a *new* transaction starts (REQUIRES_NEW, or REQUIRED with no enclosing tx). So a `scope="transaction"` component is one instance per transaction (Unit-of-Work / identity-map), released with its `@cleanup` hooks when the tx ends. The session ContextVar and the DI scope are two facets of one boundary
 - **`get_session(manager)`**: Returns current session from active transaction context
-- **Non-transactional paths** (NEVER, NOT_SUPPORTED, SUPPORTS without tx): Still set `TransactionContext` so `get_session()` works
+- **Non-transactional paths** (NEVER, NOT_SUPPORTED, SUPPORTS without tx): Still set `TransactionContext` so `get_session()` works, but open no DI `"transaction"` scope (resolving a `scope="transaction"` component there raises `ScopeError`)
 
 ## Code Style
 
@@ -59,4 +60,4 @@ src/pico_sqlalchemy/
 
 - Do not modify `_version.py`
 - Do not add `@component` to `SessionManager` (factory creates it)
-- `_tx_context` ContextVar is intentional and separate from pico-ioc scope system
+- `_tx_context` (session propagation) and the pico-ioc `"transaction"` DI scope are bound to one boundary by `TransactionalInterceptor` — keep them coordinated; do not reintroduce a second, independent transaction concept

{pico_sqlalchemy-0.3.0/docs → pico_sqlalchemy-0.5.0}/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.h
 
 ---
 
+## [0.5.0] - 2026-07-10
+
+### Added
+
+- `AlembicMigrator`: runs `alembic upgrade` at container startup when `database.migrations_path` points to an Alembic script directory (`migrations_target` selects the revision, default `head`). Optional extra: `pico-sqlalchemy[migrations]`.
+
+---
+
+## [0.4.0] - 2026-06-07
+
+### Added
+- **Transaction-scoped DI**: `TransactionalInterceptor` now binds pico-ioc's `"transaction"` DI scope to the database transaction boundary. When a *new* transaction starts (`REQUIRES_NEW`, or `REQUIRED` with no enclosing transaction) it activates a fresh `"transaction"` scope (via `container.scope(..., cleanup=True)`) for the duration of the call, so components registered with `scope="transaction"` live exactly one transaction and run their `@cleanup` hooks when it ends. Joins reuse the enclosing scope. Requires **pico-ioc >= 2.2.6**.
+- `tests/test_transaction_scope.py`: covers one-instance-per-transaction, sharing within a transaction, `REQUIRES_NEW` scope push/restore, fail-fast resolution outside a transaction, and `@cleanup` on transaction end.
+
+### Changed
+- Bumped `pico-ioc` dependency to `>= 2.2.6`.
+
+---
+
 ## [0.3.0] - 2026-02-20
 
 ### Changed

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.5.0}/CLAUDE.md

@@ -10,10 +10,10 @@ pico-sqlalchemy provides SQLAlchemy integration for pico-ioc. It uses:
 
 ## Key Reminders
 
-- pico-ioc dependency: `>= 2.2.0`
+- pico-ioc dependency: `>= 2.2.6` (needs `container.scope(..., cleanup=True)`)
 - **NEVER change `version_scheme`** in pyproject.toml. It MUST remain `"post-release"`. Changing it to `"guess-next-dev"` causes `.dev0` versions to leak to PyPI. This was already fixed once — do not revert it.
 - requires-python >= 3.11
 - Commit messages: one line only
 - `@transactional` works both with and without parentheses (like `@repository`)
 - `SessionManager` has NO `@component` decorator - it's created by the factory
-- `_tx_context` ContextVar is for session propagation, NOT the same as pico-ioc's "transaction" scope
+- `_tx_context` ContextVar is the *session* side of a transaction (propagation across nested calls). `TransactionalInterceptor` binds pico-ioc's `"transaction"` DI scope to the *same* boundary: when a new transaction starts (REQUIRES_NEW, or REQUIRED with no enclosing tx) it activates a fresh `"transaction"` scope (with `cleanup=True`) for the call, so `scope="transaction"` components live exactly one transaction. They are two facets of one boundary, not separate mechanisms.

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-sqlalchemy
-Version: 0.3.0
+Version: 0.5.0
 Summary: Pico-ioc integration for SQLAlchemy. Adds Spring-style transactional support, configuration, and helpers.
 Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
 License: MIT License
@@ -47,17 +47,20 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pico-ioc>=2.2.0
+Requires-Dist: pico-ioc>=2.2.6
 Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: migrations
+Requires-Dist: alembic>=1.13; extra == "migrations"
 Provides-Extra: async
 Requires-Dist: asyncpg>=0.29.0; extra == "async"
 Provides-Extra: test
 Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: alembic>=1.13; extra == "test"
 Requires-Dist: pytest-asyncio>=0.23.5; extra == "test"
 Requires-Dist: pytest-cov>=5; extra == "test"
 Dynamic: license-file
 
-# 📦 pico-sqlalchemy
+# pico-sqlalchemy
 
 [![PyPI](https://img.shields.io/pypi/v/pico-sqlalchemy.svg)](https://pypi.org/project/pico-sqlalchemy/)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/dperezcabrera/pico-sqlalchemy)
@@ -68,6 +71,7 @@ Dynamic: license-file
 [![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-sqlalchemy\&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-sqlalchemy)
 [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-sqlalchemy\&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-sqlalchemy)
 [![Docs](https://img.shields.io/badge/Docs-pico--sqlalchemy-blue?style=flat&logo=readthedocs&logoColor=white)](https://dperezcabrera.github.io/pico-sqlalchemy/)
+[![Interactive Lab](https://img.shields.io/badge/Learn-online-green?style=flat&logo=python&logoColor=white)](https://dperezcabrera.github.io/pico-learn/)
 
 # Pico-SQLAlchemy
 
@@ -75,14 +79,14 @@ Dynamic: license-file
 
 It brings constructor-based dependency injection, **implicit transaction management**, and powerful **declarative queries** using pure Python and SQLAlchemy’s Async ORM.
 
-> 🐍 **Requires Python 3.11+**
-> 🚀 **Async-Native:** Built entirely on `AsyncSession` and `create_async_engine`.
-> ✨ **Zero-Boilerplate:** Repositories are transactional by default.
-> 🔍 **Declarative Queries:** Define SQL or expressions in decorators; the library executes them for you.
+> **Requires Python 3.11+**
+> **Async-Native:** Built entirely on `AsyncSession` and `create_async_engine`.
+> **Zero-Boilerplate:** Repositories are transactional by default.
+> **Declarative Queries:** Define SQL or expressions in decorators; the library executes them for you.
 
 ---
 
-## 🎯 Why pico-sqlalchemy?
+## Why pico-sqlalchemy?
 
 Most Python apps suffer from manual session handling (`async with session...`), scattered transaction logic, and verbose repository patterns.
 
@@ -98,7 +102,7 @@ Most Python apps suffer from manual session handling (`async with session...`),
 
 ---
 
-## 🧱 Core Features
+## Core Features
 
 * **Implicit Transactions:** Methods inside `@repository` are automatically **Read-Write** transactional.
 * **Declarative Queries:** Use `@query` to run SQL or Expressions automatically (defaults to **Read-Only**).
@@ -108,7 +112,7 @@ Most Python apps suffer from manual session handling (`async with session...`),
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
 pip install pico-sqlalchemy
@@ -123,7 +127,7 @@ pip install asyncpg     # for PostgreSQL
 
 -----
 
-## 🚀 Quick Example
+## Quick Example
 
 ### 1\. Define Model
 
@@ -218,7 +222,7 @@ if __name__ == "__main__":
 
 -----
 
-## ⚡ Transaction Hierarchy & Rules
+## Transaction Hierarchy & Rules
 
 Pico-SQLAlchemy applies a "Best Effort" strategy to determine transaction configuration. The priority order (highest wins) is:
 
@@ -236,7 +240,7 @@ Pico-SQLAlchemy applies a "Best Effort" strategy to determine transaction config
     async def update_user(self): ...
     ```
 
-    👉 **Result:** Active Read-Write Transaction (Implicit from `@repository`).
+    **Result:** Active Read-Write Transaction (Implicit from `@repository`).
 
 2.  **Query Method:**
 
@@ -245,7 +249,7 @@ Pico-SQLAlchemy applies a "Best Effort" strategy to determine transaction config
     async def get_data(self): ...
     ```
 
-    👉 **Result:** Active Read-Only Transaction (Implicit from `@query`).
+    **Result:** Active Read-Only Transaction (Implicit from `@query`).
 
 3.  **Manual Override:**
 
@@ -254,11 +258,29 @@ Pico-SQLAlchemy applies a "Best Effort" strategy to determine transaction config
     async def complex_report(self): ...
     ```
 
-    👉 **Result:** Active Read-Only Transaction (Explicit override).
+    **Result:** Active Read-Only Transaction (Explicit override).
+
+### Transaction-scoped components *(v0.4.0+)*
+
+Beyond managing the SQLAlchemy session, the interceptor binds pico-ioc's **`"transaction"` DI scope** to the same boundary. A component registered with `scope="transaction"` is instantiated **once per database transaction** and torn down (running its `@cleanup` hooks) when that transaction ends:
+
+```python
+@component(scope="transaction")
+class UnitOfWorkAudit:
+    def __init__(self):
+        self.events: list[str] = []
+
+    @cleanup
+    def flush(self):
+        # runs exactly when the enclosing transaction ends
+        ...
+```
+
+A **new** transaction (`REQUIRES_NEW`, or `REQUIRED` with no enclosing transaction) opens a fresh scope; **joins reuse** the enclosing one — so the session boundary and the DI lifetime are two facets of a single transaction. Requires **pico-ioc ≥ 2.2.6**.
 
 -----
 
-## 🔍 Declarative Queries in Depth
+## Declarative Queries in Depth
 
 The `@query` decorator eliminates boilerplate for common fetches.
 
@@ -293,7 +315,7 @@ async def find_active(self, page: PageRequest) -> Page[User]: ...
 
 -----
 
-## 🧪 Testing
+## Testing
 
 Testing is simple because you can override the configuration or the components easily using Pico-IoC.
 
@@ -311,7 +333,7 @@ async def test_service():
 
 -----
 
-## 💡 Architecture Overview
+## Architecture Overview
 
 ```
                  ┌─────────────────────────────┐
@@ -349,7 +371,7 @@ curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/instal
 |---------|-------------|
 | `/add-repository` | Add SQLAlchemy entities and repositories with transactions |
 | `/add-component` | Add components, factories, interceptors, settings |
-| `/add-tests` | Generate tests for pico-framework components |
+| `/add-tests` | Generate tests for pico components |
 
 All skills: `curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash`
 
@@ -357,6 +379,6 @@ See [pico-skills](https://github.com/dperezcabrera/pico-skills) for details.
 
 ---
 
-## 📝 License
+## License
 
 MIT

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.5.0}/README.md

@@ -1,4 +1,4 @@
-# 📦 pico-sqlalchemy
+# pico-sqlalchemy
 
 [![PyPI](https://img.shields.io/pypi/v/pico-sqlalchemy.svg)](https://pypi.org/project/pico-sqlalchemy/)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/dperezcabrera/pico-sqlalchemy)
@@ -9,6 +9,7 @@
 [![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-sqlalchemy\&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-sqlalchemy)
 [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-sqlalchemy\&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-sqlalchemy)
 [![Docs](https://img.shields.io/badge/Docs-pico--sqlalchemy-blue?style=flat&logo=readthedocs&logoColor=white)](https://dperezcabrera.github.io/pico-sqlalchemy/)
+[![Interactive Lab](https://img.shields.io/badge/Learn-online-green?style=flat&logo=python&logoColor=white)](https://dperezcabrera.github.io/pico-learn/)
 
 # Pico-SQLAlchemy
 
@@ -16,14 +17,14 @@
 
 It brings constructor-based dependency injection, **implicit transaction management**, and powerful **declarative queries** using pure Python and SQLAlchemy’s Async ORM.
 
-> 🐍 **Requires Python 3.11+**
-> 🚀 **Async-Native:** Built entirely on `AsyncSession` and `create_async_engine`.
-> ✨ **Zero-Boilerplate:** Repositories are transactional by default.
-> 🔍 **Declarative Queries:** Define SQL or expressions in decorators; the library executes them for you.
+> **Requires Python 3.11+**
+> **Async-Native:** Built entirely on `AsyncSession` and `create_async_engine`.
+> **Zero-Boilerplate:** Repositories are transactional by default.
+> **Declarative Queries:** Define SQL or expressions in decorators; the library executes them for you.
 
 ---
 
-## 🎯 Why pico-sqlalchemy?
+## Why pico-sqlalchemy?
 
 Most Python apps suffer from manual session handling (`async with session...`), scattered transaction logic, and verbose repository patterns.
 
@@ -39,7 +40,7 @@ Most Python apps suffer from manual session handling (`async with session...`),
 
 ---
 
-## 🧱 Core Features
+## Core Features
 
 * **Implicit Transactions:** Methods inside `@repository` are automatically **Read-Write** transactional.
 * **Declarative Queries:** Use `@query` to run SQL or Expressions automatically (defaults to **Read-Only**).
@@ -49,7 +50,7 @@ Most Python apps suffer from manual session handling (`async with session...`),
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
 pip install pico-sqlalchemy
@@ -64,7 +65,7 @@ pip install asyncpg     # for PostgreSQL
 
 -----
 
-## 🚀 Quick Example
+## Quick Example
 
 ### 1\. Define Model
 
@@ -159,7 +160,7 @@ if __name__ == "__main__":
 
 -----
 
-## ⚡ Transaction Hierarchy & Rules
+## Transaction Hierarchy & Rules
 
 Pico-SQLAlchemy applies a "Best Effort" strategy to determine transaction configuration. The priority order (highest wins) is:
 
@@ -177,7 +178,7 @@ Pico-SQLAlchemy applies a "Best Effort" strategy to determine transaction config
     async def update_user(self): ...
     ```
 
-    👉 **Result:** Active Read-Write Transaction (Implicit from `@repository`).
+    **Result:** Active Read-Write Transaction (Implicit from `@repository`).
 
 2.  **Query Method:**
 
@@ -186,7 +187,7 @@ Pico-SQLAlchemy applies a "Best Effort" strategy to determine transaction config
     async def get_data(self): ...
     ```
 
-    👉 **Result:** Active Read-Only Transaction (Implicit from `@query`).
+    **Result:** Active Read-Only Transaction (Implicit from `@query`).
 
 3.  **Manual Override:**
 
@@ -195,11 +196,29 @@ Pico-SQLAlchemy applies a "Best Effort" strategy to determine transaction config
     async def complex_report(self): ...
     ```
 
-    👉 **Result:** Active Read-Only Transaction (Explicit override).
+    **Result:** Active Read-Only Transaction (Explicit override).
+
+### Transaction-scoped components *(v0.4.0+)*
+
+Beyond managing the SQLAlchemy session, the interceptor binds pico-ioc's **`"transaction"` DI scope** to the same boundary. A component registered with `scope="transaction"` is instantiated **once per database transaction** and torn down (running its `@cleanup` hooks) when that transaction ends:
+
+```python
+@component(scope="transaction")
+class UnitOfWorkAudit:
+    def __init__(self):
+        self.events: list[str] = []
+
+    @cleanup
+    def flush(self):
+        # runs exactly when the enclosing transaction ends
+        ...
+```
+
+A **new** transaction (`REQUIRES_NEW`, or `REQUIRED` with no enclosing transaction) opens a fresh scope; **joins reuse** the enclosing one — so the session boundary and the DI lifetime are two facets of a single transaction. Requires **pico-ioc ≥ 2.2.6**.
 
 -----
 
-## 🔍 Declarative Queries in Depth
+## Declarative Queries in Depth
 
 The `@query` decorator eliminates boilerplate for common fetches.
 
@@ -234,7 +253,7 @@ async def find_active(self, page: PageRequest) -> Page[User]: ...
 
 -----
 
-## 🧪 Testing
+## Testing
 
 Testing is simple because you can override the configuration or the components easily using Pico-IoC.
 
@@ -252,7 +271,7 @@ async def test_service():
 
 -----
 
-## 💡 Architecture Overview
+## Architecture Overview
 
 ```
                  ┌─────────────────────────────┐
@@ -290,7 +309,7 @@ curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/instal
 |---------|-------------|
 | `/add-repository` | Add SQLAlchemy entities and repositories with transactions |
 | `/add-component` | Add components, factories, interceptors, settings |
-| `/add-tests` | Generate tests for pico-framework components |
+| `/add-tests` | Generate tests for pico components |
 
 All skills: `curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash`
 
@@ -298,6 +317,6 @@ See [pico-skills](https://github.com/dperezcabrera/pico-skills) for details.
 
 ---
 
-## 📝 License
+## License
 
 MIT

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.5.0/docs}/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.h
 
 ---
 
+## [0.5.0] - 2026-07-10
+
+### Added
+
+- `AlembicMigrator`: runs `alembic upgrade` at container startup when `database.migrations_path` points to an Alembic script directory (`migrations_target` selects the revision, default `head`). Optional extra: `pico-sqlalchemy[migrations]`.
+
+---
+
+## [0.4.0] - 2026-06-07
+
+### Added
+- **Transaction-scoped DI**: `TransactionalInterceptor` now binds pico-ioc's `"transaction"` DI scope to the database transaction boundary. When a *new* transaction starts (`REQUIRES_NEW`, or `REQUIRED` with no enclosing transaction) it activates a fresh `"transaction"` scope (via `container.scope(..., cleanup=True)`) for the duration of the call, so components registered with `scope="transaction"` live exactly one transaction and run their `@cleanup` hooks when it ends. Joins reuse the enclosing scope. Requires **pico-ioc >= 2.2.6**.
+- `tests/test_transaction_scope.py`: covers one-instance-per-transaction, sharing within a transaction, `REQUIRES_NEW` scope push/restore, fail-fast resolution outside a transaction, and `@cleanup` on transaction end.
+
+### Changed
+- Bumped `pico-ioc` dependency to `>= 2.2.6`.
+
+---
+
 ## [0.3.0] - 2026-02-20
 
 ### Changed

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.5.0}/docs/architecture.md

@@ -118,7 +118,7 @@ pico-sqlalchemy uses a `ContextVar` to propagate the active session across async
 _tx_context: ContextVar[TransactionContext | None]
 ```
 
-This is **separate from pico-ioc's scope system**. It is a lightweight, per-async-task variable that stores the currently active `AsyncSession` wrapped in a `TransactionContext`.
+This is the **session** side of a transaction: a lightweight, per-async-task variable that stores the currently active `AsyncSession` wrapped in a `TransactionContext`. It is paired with the pico-ioc `"transaction"` DI scope (the **component** side — see below), bound to the same boundary by `TransactionalInterceptor`.
 
 **How it works:**
 
@@ -140,7 +140,31 @@ Service.create_user()                     ← @transactional
    _tx_context = None
 ```
 
-**Why not pico-ioc scopes?** The `_tx_context` ContextVar provides transaction propagation semantics (REQUIRED, REQUIRES_NEW, etc.) that don't map to pico-ioc's scope lifecycle. A transaction may be suspended and restored (REQUIRES_NEW, NOT_SUPPORTED), which requires explicit save/restore of the context — something ContextVar handles naturally.
+**Why a ContextVar for the session?** Transaction propagation (REQUIRED, REQUIRES_NEW, etc.) needs to suspend and restore the active session (REQUIRES_NEW, NOT_SUPPORTED) — something a `ContextVar` handles naturally, save/restore via tokens.
+
+### The paired `"transaction"` DI scope
+
+`TransactionalInterceptor` also binds pico-ioc's `"transaction"` **DI scope** to the same boundary. Whenever a *new* transaction is born — `REQUIRES_NEW`, or `REQUIRED` with no enclosing transaction — it activates a fresh `"transaction"` scope (with `cleanup=True`) around the call:
+
+```text
+Service.create_user()                     ← @transactional REQUIRED (new tx)
+│  activate "transaction" scope  (id = T1)         _tx_context = session_A
+│
+├─ container.get(AuditLog)  → scope="transaction"  ← created once, id T1
+├─ container.get(AuditLog)  → same instance        ← joined: same T1
+│
+├─ Other.in_new_tx()                      ← @transactional REQUIRES_NEW
+│  │  activate "transaction" scope (id = T2)        _tx_context = session_B
+│  └─ container.get(AuditLog) → NEW instance        ← isolated in T2
+│     deactivate T2 (+ @cleanup), restore T1, session_A
+│
+└─ commit / rollback
+   deactivate T1 (runs @cleanup on T1's components), _tx_context = None
+```
+
+So a `scope="transaction"` component is **one instance per transaction** — a Unit-of-Work / identity-map that is released (running its `@cleanup` hooks) when the transaction ends. Joins reuse the enclosing instance; `REQUIRES_NEW` gets its own and restores the outer one afterwards. Non-transactional paths (`NEVER`, `NOT_SUPPORTED`, `SUPPORTS` without a tx) open no scope — resolving a `scope="transaction"` component there raises `ScopeError`.
+
+> The scope is bound at the interceptor (which wraps the call directly), not deep inside `SessionManager`: a `ContextVar` set inside the transaction async-generator does not reliably reach the method body across nesting. As with any AOP, **self-invocation bypasses it** — `REQUIRES_NEW` only opens a new transaction/scope when the method is called on another injected component, not via `self.method()`.
 
 ---
 

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.5.0}/docs/hooks.py

@@ -5,4 +5,3 @@ import logging
 # griffe's logger is patched by mkdocstrings to use mkdocs.plugins.* namespace.
 for name in ("griffe", "mkdocs.plugins.griffe", "_griffe"):
     logging.getLogger(name).setLevel(logging.ERROR)
-