rowquery 0.1.2__tar.gz → 0.2.0__tar.gz

{rowquery-0.1.2 → rowquery-0.2.0}/.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
 blank_issues_enabled: false
 contact_links:
   - name: Question or Discussion
-    url: https://github.com/maksim-shevtsov/RowQuery/discussions
+    url: https://github.com/MaksimShevtsov/RowQuery/discussions
     about: Ask questions or discuss ideas

rowquery-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,115 @@
+name: Tests
+
+on:
+  push:
+    branches: [main, "001-*"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra sqlite --extra dev
+
+      - name: Run unit and contract tests
+        run: uv run pytest tests/unit/ tests/contract/ -v --cov=row_query --cov-report=xml --cov-report=term
+
+      - name: Run integration tests
+        run: uv run pytest tests/integration/ -m integration -v
+
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false
+
+  integration-servers:
+    name: Integration (PostgreSQL + MySQL + Oracle)
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_PASSWORD: rowquery
+          POSTGRES_DB: rowquery
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+      mysql:
+        image: mysql:8.4
+        env:
+          MYSQL_ROOT_PASSWORD: rowquery
+          MYSQL_DATABASE: rowquery
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd "mysqladmin ping -prowquery --silent"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+      oracle:
+        image: gvenzl/oracle-free:23-slim-faststart
+        env:
+          ORACLE_PASSWORD: rowquery
+          APP_USER: rowquery
+          APP_USER_PASSWORD: rowquery
+        ports:
+          - 1521:1521
+        options: >-
+          --health-cmd healthcheck.sh
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 30
+
+    env:
+      ROWQUERY_TEST_POSTGRESQL: postgresql://postgres:rowquery@127.0.0.1:5432/rowquery
+      ROWQUERY_TEST_MYSQL: mysql://root:rowquery@127.0.0.1:3306/rowquery
+      ROWQUERY_TEST_ORACLE: oracle://rowquery:rowquery@127.0.0.1:1521/FREEPDB1
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --extra all --extra dev
+
+      - name: Run server integration tests
+        run: uv run pytest tests/integration/test_server_backends.py -m integration -v -rs

rowquery-0.2.0/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-21
+
+### Fixed
+- **Transaction state no longer leaks between calls.** Connections are rolled back when they return to the pool, so reads no longer leave PostgreSQL sessions `idle in transaction`, MySQL `REPEATABLE READ` readers no longer see a stale snapshot, and a failed statement no longer leaves a PostgreSQL connection in the `current transaction is aborted` state.
+- **Real connection pooling.** The pool now waits for a free connection (up to `pool_timeout`) instead of raising `RuntimeError` when exhausted, opens connections lazily, honours `pool_recycle`, and discards connections that fail the reset or are reported broken. `Engine` can be used from several threads (SQLite connections are opened with `check_same_thread=False`), and `asyncio.gather` with more tasks than `pool_size` works.
+- **`%` in SQL for PostgreSQL/MySQL.** Literal `%` (e.g. `LIKE 'a%'`) is escaped when `:name` placeholders are converted to `%(name)s`.
+- **Migrations**: files may contain several statements; versions are ordered numerically (`9_x` before `10_y`); the tracking table and inserts work on PostgreSQL, MySQL and Oracle; duplicate version numbers are rejected.
+- **SQLSanitizer bypasses**: constructs whose extent differs between MySQL and PostgreSQL are rejected (backslashes inside any quoted literal or identifier, dollar-quoted strings, `#` outside literals, `--` not followed by whitespace, `
+` inside `--` comments); the `allowed_verbs` check skips leading comments and rejects SQL whose verb cannot be determined (fail-closed); MySQL `/*! ... */` executable comments are rejected when comments are not stripped; unterminated block comments are rejected.
+- `Engine.transaction()` acquires its connection on `__enter__` instead of at call time.
+- Transactions now have the same query API as engines: `fetch_one` raises `MultipleRowsError`, plus `mapper=` and `fetch_scalar`.
+- `fetch_one` reads at most two rows instead of the whole result.
+- MySQL cursors are buffered and always closed, avoiding `Unread result found` after `fetch_scalar`/`fetch_one`.
+- PostgreSQL connection strings are built with `psycopg.conninfo.make_conninfo` (passwords with spaces or quotes work); `ConnectionConfig.extra` is passed to every driver.
+- Oracle: DSN defaults to port 1521 when `port` is unset; only ALL-CAPS column names are lowercased, so quoted mixed-case aliases are preserved.
+- Single-word inline SQL (`VACUUM`, `COMMIT`) is no longer mistaken for a registry key.
+- SQLite transactions and migrations now cover DDL: an explicit `BEGIN` is issued, so a failing transaction or migration rolls back `CREATE`/`ALTER`/`DROP` too (the `sqlite3` module only opens transactions implicitly before DML).
+- A connection released after `close_pool()` is closed instead of being handed to the new pool; pool initialisation is thread-safe.
+- MySQL connection liveness is checked locally instead of pinging the server on every acquire; pool health checks run outside the pool lock.
+- Applied migrations are matched by version number, so renaming `9_x.sql` to `009_x.sql` does not re-apply it.
+- Parameter conversion honours the backend's string-literal rules (`'C:\'` is a complete literal on PostgreSQL).
+- Strict aggregate mapping also validates reference and value-object columns.
+- Project URLs in `pyproject.toml` point to the correct GitHub repository.
+
+### Added
+- **Nested collections** in aggregate mappings: `.collection("lines.discounts", Discount, prefix="disc__", key="id")` nests a collection inside a previously declared one, at any depth. Children are deduplicated per parent instance; strict mode validates nested columns, prefixes and identity key columns (root, collections at every level, references) and reports collections by their full path. Dotted paths for `reference()` / `value_object()` are rejected at `build()`. `CollectionPlan.children` is now populated and used by `AggregateMapper`.
+- Portable positional placeholders: `?` is converted to `%s` (PostgreSQL, MySQL) or `:1, :2, ...` (Oracle); `??` is a literal `?` (e.g. the PostgreSQL JSONB operator). SQL already using native `%s` / `%(name)s` placeholders is passed through unchanged.
+- `QueryExecutionError` (database rejected the query) and `IntegrityError` (constraint violation), both carrying the driver exception as `__cause__`; `PoolTimeoutError`.
+- `Engine.close()` / `AsyncEngine.close()`; `ConnectionManager.acquire()` / `release()`.
+- CI runs the integration suite against PostgreSQL, MySQL and Oracle (23ai Free) service containers.
+
+### Changed
+- **Breaking:** errors that are not binding problems now raise `QueryExecutionError` instead of `ParameterBindingError` (which is now a subclass of `QueryExecutionError`). Catch `ExecutionError` or `QueryExecutionError` to handle all database errors.
+- **Breaking (adapter protocol):** adapters now implement `connect`/`close_connection`/`is_connection_alive`/`execute` (async: `connect_async`/`close_connection_async`/`execute_async`) plus `begin`/`begin_async`, `positional_paramstyle` and `backslash_escapes`; pooling moved into `row_query.core.pool`. `TransactionManager`/`AsyncTransactionManager` take a connection manager instead of a raw connection.
+- `ConnectionConfig.pool_timeout` and `pool_recycle` are floats and are now enforced.
+
+## [0.1.2] - 2026-02-22
+
+### Added
+- **Inline SQL support**: All engine and transaction methods (`fetch_one`, `fetch_all`, `fetch_scalar`, `execute`) now accept raw SQL strings in addition to registry keys. A string containing whitespace is treated as inline SQL; a dot-separated identifier like `user.get_by_id` is resolved from the registry.
+- **Flexible parameter binding**: `params` argument now accepts `dict` (named), `tuple`/`list` (positional), or a single scalar value (automatically wrapped in a tuple). Previously only `dict | None` was accepted.
+- **`SQLSanitizer`** — configurable sanitizer applied to inline SQL before execution:
+  - `strip_comments` (default `True`): removes `--` line comments and `/* */` block comments while preserving string literals.
+  - `block_multiple_statements` (default `True`): rejects SQL containing a statement-terminating `;` followed by additional content (prevents query stacking attacks).
+  - `allowed_verbs` (default `None`): restricts the leading SQL keyword to a caller-supplied `frozenset` (e.g. `frozenset({"SELECT"})`). Registry queries are never sanitized.
+- **`SQLSanitizationError`** exception (subclass of `ExecutionError`) raised when a sanitization check fails.
+- **`is_raw_sql()`** and **`coerce_params()`** helpers exported from `row_query.core.params`.
+- 65 new unit tests covering all sanitizer behaviour (`tests/unit/test_sanitizer.py`).
+
+## [0.1.0] - 2025-02-16
+
+### Added
+- Initial alpha release
+- Core query execution engine (`Engine`, `AsyncEngine`)
+- Connection management with pooling support (`ConnectionManager`, `AsyncConnectionManager`)
+- Multi-database adapter pattern supporting SQLite, PostgreSQL, MySQL, and Oracle
+- SQL registry for loading `.sql` files into dot-separated namespaces (`SQLRegistry`)
+- Parameter normalization supporting `:name` syntax across all database backends
+- Model mapping for dataclasses, Pydantic models, and plain classes (`ModelMapper`)
+- Aggregate mapping for complex object graph reconstruction with single-pass O(n) algorithm
+- Collection mapping for one-to-many relationships in aggregate patterns
+- Value object mapping for embedded entities in aggregates
+- Reference mapping for foreign key relationships
+- Transaction management with context manager support (`TransactionManager`, `AsyncTransactionManager`)
+- Migration management system with version tracking (`MigrationManager`, `MigrationInfo`)
+- Repository pattern base classes for DDD-style code organization (`Repository`, `AsyncRepository`)
+- Comprehensive exception hierarchy with 18 custom exception classes
+- Full type safety with mypy strict mode compliance
+- Support for Python 3.10, 3.11, 3.12, and 3.13
+- 125 unit, contract, and integration tests
+
+[Unreleased]: https://github.com/MaksimShevtsov/RowQuery/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/MaksimShevtsov/RowQuery/releases/tag/v0.2.0
+[0.1.2]: https://github.com/MaksimShevtsov/RowQuery/releases/tag/v0.1.2
+[0.1.1]: https://github.com/MaksimShevtsov/RowQuery/releases/tag/v0.1.1
+[0.1.0]: https://github.com/MaksimShevtsov/RowQuery/releases/tag/v0.1.0

{rowquery-0.1.2 → rowquery-0.2.0}/CLAUDE.md

@@ -19,7 +19,9 @@ uv sync --extra all        # Install all database drivers
 ## Commands
 
 ```bash
-uv run pytest              # Run all tests (125 tests)
+uv run pytest              # Run all tests
+# Server integration tests run when ROWQUERY_TEST_POSTGRESQL / ROWQUERY_TEST_MYSQL
+# are set to postgresql://user:pw@host:port/db and mysql://user:pw@host:port/db URLs
 uv run pytest tests/unit/  # Unit tests only
 uv run pytest tests/contract/  # Protocol contract tests
 uv run pytest tests/integration/  # SQLite integration tests
@@ -32,13 +34,17 @@ uv run mypy row_query/     # Type check (strict mode)
 
 - **`row_query/core/`** — Core engine
   - `connection.py` — `ConnectionConfig` (Pydantic), `ConnectionManager`, `AsyncConnectionManager`
+  - `pool.py` — `SyncPool`/`AsyncPool`: bounded, lazy, timeout + recycle, rollback on release
+  - `execution.py` — `SyncExecutor`/`AsyncExecutor` (query API shared by engines and transactions), driver error translation
   - `engine.py` — `Engine` and `AsyncEngine` (fetch_one, fetch_all, fetch_scalar, execute, transaction)
   - `registry.py` — `SQLRegistry` (loads .sql files into dot-separated namespaces)
   - `transaction.py` — `TransactionManager`, `AsyncTransactionManager`
   - `migration.py` — `MigrationManager`, `MigrationInfo`
-  - `params.py` — `:name` → `%(name)s` parameter normalizer with cache
+  - `params.py` — `:name`/`?` → driver placeholder conversion (escapes `%` for pyformat)
+  - `lexer.py` — SQL tokenizer (strings, `$$`, `E''`, identifiers, comments) and statement splitter
+  - `sanitizer.py` — fail-closed `SQLSanitizer` for inline SQL
   - `enums.py` — `DatabaseBackend` enum
-  - `exceptions.py` — Full exception hierarchy (18 classes)
+  - `exceptions.py` — Full exception hierarchy
 
 - **`row_query/adapters/`** — Database drivers
   - `protocol.py` — `SyncAdapter`, `AsyncAdapter` runtime-checkable protocols

{rowquery-0.1.2 → rowquery-0.2.0}/CONTRIBUTING.md

@@ -13,7 +13,7 @@ Thank you for your interest in contributing! This document provides guidelines f
 
 ```bash
 # Clone repository
-git clone https://github.com/maksim-shevtsov/RowQuery.git
+git clone https://github.com/MaksimShevtsov/RowQuery.git
 cd RowQuery
 
 # Install all dependencies (including all database drivers)

{rowquery-0.1.2 → rowquery-0.2.0}/PKG-INFO

@@ -1,12 +1,12 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: rowquery
-Version: 0.1.2
+Version: 0.2.0
 Summary: A SQL-first Python library for querying and mapping data across multiple database backends.
-Project-URL: Homepage, https://github.com/maksim-shevtsov/RowQuery
-Project-URL: Documentation, https://github.com/maksim-shevtsov/RowQuery#readme
-Project-URL: Repository, https://github.com/maksim-shevtsov/RowQuery.git
-Project-URL: Issues, https://github.com/maksim-shevtsov/RowQuery/issues
-Project-URL: Changelog, https://github.com/maksim-shevtsov/RowQuery/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/MaksimShevtsov/RowQuery
+Project-URL: Documentation, https://github.com/MaksimShevtsov/RowQuery#readme
+Project-URL: Repository, https://github.com/MaksimShevtsov/RowQuery.git
+Project-URL: Issues, https://github.com/MaksimShevtsov/RowQuery/issues
+Project-URL: Changelog, https://github.com/MaksimShevtsov/RowQuery/blob/main/CHANGELOG.md
 Author-email: Maksim Shevtsov <maksim.shautsou.dev@gmail.com>
 License: MIT
 License-File: LICENSE
@@ -52,8 +52,8 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://badge.fury.io/py/rowquery.svg)](https://pypi.org/project/rowquery/)
 [![Python Versions](https://img.shields.io/pypi/pyversions/rowquery.svg)](https://pypi.org/project/rowquery/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Tests](https://github.com/maksim-shevtsov/RowQuery/workflows/Tests/badge.svg)](https://github.com/maksim-shevtsov/RowQuery/actions)
-[![codecov](https://codecov.io/gh/maksim-shevtsov/RowQuery/branch/main/graph/badge.svg)](https://codecov.io/gh/maksim-shevtsov/RowQuery)
+[![Tests](https://github.com/MaksimShevtsov/RowQuery/actions/workflows/test.yml/badge.svg)](https://github.com/MaksimShevtsov/RowQuery/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/MaksimShevtsov/RowQuery/branch/main/graph/badge.svg)](https://codecov.io/gh/MaksimShevtsov/RowQuery)
 [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
 
 A SQL-first Python library for querying and mapping data across multiple database backends.
@@ -119,6 +119,10 @@ count = engine.fetch_scalar("SELECT COUNT(*) FROM users")
 rows = engine.fetch_all("SELECT * FROM users WHERE id IN (?, ?)", [1, 2])
 ```
 
+Placeholders are portable: use `:name` with a dict or `?` with positional values on any
+backend. RowQuery converts them to the driver's native style (`%(name)s` / `%s` for
+PostgreSQL and MySQL, `:1` for Oracle) and escapes literal `%` such as `LIKE 'a%'`.
+
 ### 3. Map to Models
 ```python
 from dataclasses import dataclass

{rowquery-0.1.2 → rowquery-0.2.0}/README.md

@@ -3,8 +3,8 @@
 [![PyPI version](https://badge.fury.io/py/rowquery.svg)](https://pypi.org/project/rowquery/)
 [![Python Versions](https://img.shields.io/pypi/pyversions/rowquery.svg)](https://pypi.org/project/rowquery/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Tests](https://github.com/maksim-shevtsov/RowQuery/workflows/Tests/badge.svg)](https://github.com/maksim-shevtsov/RowQuery/actions)
-[![codecov](https://codecov.io/gh/maksim-shevtsov/RowQuery/branch/main/graph/badge.svg)](https://codecov.io/gh/maksim-shevtsov/RowQuery)
+[![Tests](https://github.com/MaksimShevtsov/RowQuery/actions/workflows/test.yml/badge.svg)](https://github.com/MaksimShevtsov/RowQuery/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/MaksimShevtsov/RowQuery/branch/main/graph/badge.svg)](https://codecov.io/gh/MaksimShevtsov/RowQuery)
 [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
 
 A SQL-first Python library for querying and mapping data across multiple database backends.
@@ -70,6 +70,10 @@ count = engine.fetch_scalar("SELECT COUNT(*) FROM users")
 rows = engine.fetch_all("SELECT * FROM users WHERE id IN (?, ?)", [1, 2])
 ```
 
+Placeholders are portable: use `:name` with a dict or `?` with positional values on any
+backend. RowQuery converts them to the driver's native style (`%(name)s` / `%s` for
+PostgreSQL and MySQL, `:1` for Oracle) and escapes literal `%` such as `LIKE 'a%'`.
+
 ### 3. Map to Models
 ```python
 from dataclasses import dataclass

{rowquery-0.1.2 → rowquery-0.2.0}/llms-full.txt

@@ -4,7 +4,7 @@
 
 ## What Is RowQuery
 
-RowQuery is a Python library for executing raw SQL queries against multiple database backends with structured result mapping. It is currently in alpha (v0.1.2) and requires Python >=3.10.
+RowQuery is a Python library for executing raw SQL queries against multiple database backends with structured result mapping. It is currently in alpha (v0.2.0) and requires Python >=3.10.
 
 Key features:
 
@@ -22,7 +22,7 @@ RowQuery's core dependency is Pydantic >=2.0.0. Database-specific drivers are op
 - **Not an ORM.** RowQuery does not generate SQL from Python model definitions. You write all SQL yourself.
 - **Not a schema generator.** RowQuery does not create database tables from class definitions. Use migrations or external tools for DDL.
 - **Not a migration-only tool.** While RowQuery includes a `MigrationManager`, it is a convenience feature, not the library's primary purpose.
-- **Not a connection pooling library.** RowQuery delegates pooling to the underlying database drivers (psycopg, aiomysql, oracledb). It manages connection lifecycle but does not implement its own pool.
+- **Not a full-featured connection pooling library.** RowQuery ships a small built-in bounded pool (lazy connections, waiting with `pool_timeout`, recycling after `pool_recycle`, rollback on release). It has no pre-ping, statistics or external pooler integration.
 - **Not a query builder with DSL syntax.** There is no fluent API for constructing SQL. You pass SQL strings directly or load them from `.sql` files via `SQLRegistry`.
 - **Not a data validation framework.** RowQuery maps query results to objects but does not validate business rules or enforce constraints beyond what the database itself provides.
 
@@ -32,12 +32,12 @@ RowQuery's core dependency is Pydantic >=2.0.0. Database-specific drivers are op
 
 Install RowQuery with no database-specific drivers:
 
-```python
+```bash
 # Using uv (recommended)
-# uv add row-query
+# uv add rowquery
 
 # Using pip
-# pip install row-query
+# pip install rowquery
 ```
 
 The core installation includes only the `pydantic` dependency and the SQLite sync adapter (which uses Python's built-in `sqlite3` module).
@@ -195,16 +195,20 @@ engine = AsyncEngine.from_config(config, registry)
 AsyncEngine has identical methods, all `async`.
 
 **Query resolution:** The `query` parameter can be either:
-- A **registry key** (no whitespace): `"users.get_by_id"` — resolved via SQLRegistry.
-- **Inline SQL** (contains whitespace): `"SELECT * FROM users WHERE id = :id"` — used directly.
+- A **registry key**: a registered name or any dotted identifier such as `"users.get_by_id"` — resolved via SQLRegistry (unknown dotted keys raise `QueryNotFoundError`).
+- **Inline SQL**: anything else, e.g. `"SELECT * FROM users WHERE id = :id"` or a single-word statement such as `"VACUUM"` — used directly.
 
 **Parameter passing:** The `params` parameter accepts:
-- `dict` — Named parameters: `{"id": 1, "name": "Alice"}`
-- `tuple` or `list` — Positional parameters: `(1, "Alice")`
+- `dict` — Named parameters, written as `:name` in SQL: `{"id": 1, "name": "Alice"}`
+- `tuple` or `list` — Positional parameters, written as `?` in SQL: `(1, "Alice")`
 - Scalar value — Wrapped as `(value,)` automatically
 - `None` — No parameters (default)
 
-RowQuery automatically converts `:name` parameter syntax to the format required by each backend (`%(name)s` for PostgreSQL and MySQL, `:name` for SQLite and Oracle).
+Both placeholder styles are portable: RowQuery converts `:name` to `%(name)s` and `?` to `%s` for PostgreSQL and MySQL, and `?` to `:1, :2, ...` for Oracle. Literal `%` characters (e.g. `LIKE 'a%'`) are escaped automatically. Write `??` for a literal `?` (e.g. the PostgreSQL JSONB `?` operator) when using positional parameters. SQL already written in a driver's native style (`%s` / `%(name)s`) is passed through unchanged.
+
+**Connections and transaction state:** each engine call borrows a pooled connection. `execute()` commits immediately; any other open transaction state (read snapshots, locks, a failed statement) is rolled back when the connection returns to the pool. `Engine` can be shared between threads.
+
+**Errors:** driver exceptions are translated: constraint violations raise `IntegrityError`, binding problems `ParameterBindingError`, everything else `QueryExecutionError` (all subclasses of `ExecutionError`). The original driver exception is available as `__cause__`.
 
 **Optional SQLSanitizer:**
 
@@ -245,10 +249,10 @@ sqlite_file_config = ConnectionConfig(driver="sqlite", database="/path/to/mydb.s
 | `user` | `str \| None` | `None` | Authentication username |
 | `password` | `str \| None` | `None` | Authentication password |
 | `database` | `str` | (required) | Database name or path (`:memory:` for SQLite in-memory) |
-| `pool_size` | `int` | `5` | Maximum connections in pool |
-| `pool_timeout` | `int` | `30` | Seconds to wait for a connection from pool |
-| `pool_recycle` | `int` | `1800` | Seconds before recycling idle connections |
-| `extra` | `dict[str, Any]` | `{}` | Additional driver-specific parameters |
+| `pool_size` | `int` | `5` | Maximum open connections. Connections are opened lazily. |
+| `pool_timeout` | `float` | `30` | Seconds to wait for a free connection before raising `PoolTimeoutError`. |
+| `pool_recycle` | `float` | `1800` | Reopen connections older than this many seconds (`0` disables; ignored for SQLite). |
+| `extra` | `dict[str, Any]` | `{}` | Additional driver-specific connection arguments (passed to the driver's connect call; libpq parameters for PostgreSQL; `dsn` overrides host/port/database for Oracle). |
 
 See the Database Backends section for backend-specific ConnectionConfig examples.
 
@@ -351,7 +355,7 @@ config = ConnectionConfig(driver="sqlite", database="/path/to/mydb.sqlite")
 
 **Parameter style:** `:name` (named parameters). SQL uses `:name` syntax directly.
 
-**Adapter details:** Connections use WAL journal mode and `sqlite3.Row` row factory for dict-like access.
+**Adapter details:** Connections use WAL journal mode and `sqlite3.Row` row factory for dict-like access. They are opened with `check_same_thread=False`; the pool guarantees one thread uses a connection at a time. Note that every `:memory:` connection is a separate database, so use `pool_size=1` (or a file) for in-memory databases.
 
 ### PostgreSQL
 
@@ -376,7 +380,7 @@ config = ConnectionConfig(
 
 **Parameter style:** `pyformat`. RowQuery automatically converts `:name` in your SQL to `%(name)s` before execution.
 
-**Adapter details:** Uses `psycopg.rows.dict_row` row factory. Connection string is built from ConnectionConfig fields.
+**Adapter details:** Uses `psycopg.rows.dict_row` row factory. The connection string is built with `psycopg.conninfo.make_conninfo`, so special characters in passwords are quoted; `extra` adds libpq parameters such as `sslmode`. On Windows, async mode requires a `SelectorEventLoop`.
 
 ### MySQL
 
@@ -401,7 +405,7 @@ config = ConnectionConfig(
 
 **Parameter style:** `pyformat`. RowQuery automatically converts `:name` in your SQL to `%(name)s` before execution.
 
-**Adapter details:** Sync adapter uses `cursor(dictionary=True)`. Async adapter uses `aiomysql.DictCursor`.
+**Adapter details:** Sync adapter uses buffered `cursor(dictionary=True, buffered=True)` cursors. Async adapter uses `aiomysql.DictCursor`. Cursors are always closed after use.
 
 ### Oracle
 
@@ -424,9 +428,9 @@ config = ConnectionConfig(
 )
 ```
 
-**Parameter style:** `named`. SQL uses `:name` syntax directly (same as SQLite).
+**Parameter style:** `named`. SQL uses `:name` syntax directly (same as SQLite). Positional `?` placeholders are converted to `:1, :2, ...`.
 
-**Adapter details:** DSN format is `host:port/database`. Uses a custom row factory to convert tuples to dicts with lowercased column names.
+**Adapter details:** DSN format is `host:port/database` (port defaults to 1521; `extra={"dsn": ...}` overrides). A custom row factory converts tuples to dicts. Column names that Oracle reports in ALL CAPS (unquoted identifiers) are lowercased to match the other backends; quoted mixed-case aliases are preserved.
 
 ## Result Mapping
 
@@ -544,12 +548,55 @@ plan = (
 | `.key(field_name)` | **Required.** Sets the identity key field for the root entity. |
 | `.auto_fields()` | Auto-maps all fields of the root class (excluding collections, references, value objects). |
 | `.field(attr_name, column_name=None)` | Explicitly map a single field. `column_name` defaults to `attr_name`. |
-| `.collection(name, entity_class, prefix, key)` | Define a child collection (one-to-many). |
+| `.collection(name, entity_class, prefix, key)` | Define a child collection (one-to-many). A dotted `name` such as `"lines.discounts"` nests the collection inside a previously declared collection (any depth). |
 | `.reference(name, entity_class, prefix, key=None)` | Define a reference (many-to-one). `key` defaults to `"id"`. |
 | `.value_object(name, vo_class, prefix)` | Define an embedded value object. |
 | `.strict(enabled=True)` | Enable strict mode: validates all mapped columns exist in result set. |
 | `.build()` | Compile and return an `AggregatePlan`. Raises `PlanCompilationError` if `.key()` was not called or prefixes collide. |
 
+**Nested collections:** declare the parent collection first, then the child with a dotted path. The nested attribute (`discounts` below) is excluded from the parent entity's column mapping and initialised to an empty list.
+
+```python
+@dataclass
+class Discount:
+    id: int
+    percent: int
+
+@dataclass
+class Line:
+    id: int
+    sku: str
+    discounts: list[Discount] = field(default_factory=list)
+
+@dataclass
+class Invoice:
+    id: int
+    lines: list[Line] = field(default_factory=list)
+
+plan = (
+    aggregate(Invoice, prefix="invoice__")
+    .key("id")
+    .auto_fields()
+    .collection("lines", Line, prefix="line__", key="id")
+    .collection("lines.discounts", Discount, prefix="disc__", key="id")
+    .build()
+)
+
+invoices = engine.fetch_all(
+    """
+    SELECT i.id AS invoice__id,
+           l.id AS line__id, l.sku AS line__sku,
+           d.id AS disc__id, d.percent AS disc__percent
+    FROM invoices i
+    LEFT JOIN lines l ON l.invoice_id = i.id
+    LEFT JOIN discounts d ON d.line_id = l.id
+    """,
+    mapper=AggregateMapper(plan),
+)
+```
+
+Nested collections currently support collection members only; references and value objects are declared on the aggregate root.
+
 #### AggregateMapper
 
 AggregateMapper consumes the plan and reconstructs objects from flat rows:
@@ -584,11 +631,12 @@ orders = engine.fetch_all(
 
 **Behavior:**
 - Deduplicates root entities by key field (e.g., one Order per unique `order__id`).
-- Deduplicates collection children by their key field.
+- Deduplicates collection children by their key field, per parent instance (the same child key under two different parents yields two children).
+- Nested collections are filled recursively in the same single pass; a NULL child key skips that child and everything nested below it.
 - References and value objects are set once per root (first non-NULL occurrence).
 - Rows with NULL root key are silently skipped.
 - `map_one()` raises `NotImplementedError` — use `map_many()` only.
-- In strict mode, raises `StrictModeViolation` if columns are missing or unknown prefix groups appear.
+- In strict mode, raises `StrictModeViolation` if mapped or key columns (root, collections at every level, references) are missing, or unknown prefix groups appear.
 
 ## Transactions
 
@@ -626,11 +674,14 @@ with engine.transaction() as tx:
 
 **Available methods within a transaction:**
 
+Transactions have the same query API as the engine (including `mapper=`, `fetch_scalar` and `MultipleRowsError` from `fetch_one`); writes are committed only when the transaction commits. The connection is acquired when the `with` block is entered. On SQLite an explicit `BEGIN` is issued so DDL statements are part of the transaction.
+
 | Method | Signature | Returns |
 |--------|-----------|---------|
 | `execute` | `(query, params=None)` | `int` (affected row count) |
-| `fetch_one` | `(query, params=None)` | `dict[str, Any] \| None` |
-| `fetch_all` | `(query, params=None)` | `list[dict[str, Any]]` |
+| `fetch_one` | `(query, params=None, *, mapper=None)` | `dict`, mapped object, or `None` |
+| `fetch_all` | `(query, params=None, *, mapper=None)` | `list[dict]` or `list[T]` |
+| `fetch_scalar` | `(query, params=None)` | `Any` or `None` |
 | `commit` | `()` | `None` |
 | `rollback` | `()` | `None` |
 
@@ -727,11 +778,11 @@ version = manager.current_version()  # "003" or None if no migrations applied
 | `file_path` | `Path` | Absolute path to the `.sql` file |
 | `applied` | `bool` | Whether this migration has been applied (default: `False`) |
 
-**File naming convention:** `NNN_description.sql` where `NNN` is a zero-padded numeric version and `description` uses underscores. Files not matching this pattern raise `MigrationFileError`.
+**File naming convention:** `NNN_description.sql` where `NNN` is a numeric version and `description` uses underscores. Migrations are ordered numerically (`9_a.sql` before `10_b.sql`). Files not matching this pattern, or two files with the same number, raise `MigrationFileError`.
 
-**Tracking:** MigrationManager creates a `schema_migrations` table to track applied versions.
+**Multiple statements:** a file may contain several statements separated by `;`. Semicolons inside string literals, quoted identifiers, comments and PostgreSQL dollar-quoted bodies do not split. For procedural code with internal semicolons (MySQL/Oracle `BEGIN ... END`), add a `-- rowquery:no-split` line to run the file as a single statement.
 
-**Note:** The current implementation uses SQLite-specific SQL syntax for the tracking table. Multi-backend migration support may require adaptation.
+**Tracking:** MigrationManager creates a portable `schema_migrations` table (SQLite, PostgreSQL, MySQL, Oracle) to track applied versions. Each migration runs in one transaction with its tracking row; MySQL and Oracle commit implicitly after DDL, so a failed migration may leave earlier statements applied there.
 
 ## Repository Pattern
 
@@ -821,7 +872,9 @@ RowQueryError
 │   └── DuplicateQueryError
 ├── ExecutionError
 │   ├── MultipleRowsError
-│   ├── ParameterBindingError
+│   ├── QueryExecutionError
+│   │   ├── ParameterBindingError
+│   │   └── IntegrityError
 │   └── SQLSanitizationError
 ├── MappingError
 │   ├── ColumnMismatchError
@@ -835,6 +888,7 @@ RowQueryError
 └── AdapterError
     ├── ConnectionError
     └── PoolError
+        └── PoolTimeoutError
 ```
 
 **Detailed reference:**
@@ -847,7 +901,9 @@ RowQueryError
 | `DuplicateQueryError` | `RegistryError` | Two SQL files produce the same registry key | `query_name: str` |
 | `ExecutionError` | `RowQueryError` | Base for query execution errors | — |
 | `MultipleRowsError` | `ExecutionError` | `fetch_one()` returns more than one row | `query_name: str`, `row_count: int` |
-| `ParameterBindingError` | `ExecutionError` | Parameter binding fails during query execution | `query_name: str` |
+| `QueryExecutionError` | `ExecutionError` | The database rejects a query (syntax error, missing table, ...). Driver exception in `__cause__`. | `query_name: str`, `detail: str` |
+| `ParameterBindingError` | `QueryExecutionError` | Missing, extra or mistyped parameters | `query_name: str`, `detail: str` |
+| `IntegrityError` | `QueryExecutionError` | Constraint violation (unique, foreign key, not null, check) | `query_name: str`, `detail: str` |
 | `SQLSanitizationError` | `ExecutionError` | SQLSanitizer rejects inline SQL | — |
 | `MappingError` | `RowQueryError` | Base for result mapping errors | — |
 | `ColumnMismatchError` | `MappingError` | Row columns don't match target class fields | `target_class: str`, `missing_fields: list[str]` |
@@ -860,7 +916,8 @@ RowQueryError
 | `MigrationExecutionError` | `MigrationError` | Migration SQL execution fails | `version: str` |
 | `AdapterError` | `RowQueryError` | Base for adapter/connection errors | — |
 | `ConnectionError` | `AdapterError` | Database connection cannot be established | — |
-| `PoolError` | `AdapterError` | Connection pool error (exhausted, timeout) | — |
+| `PoolError` | `AdapterError` | Connection pool error (e.g. pool closed) | — |
+| `PoolTimeoutError` | `PoolError` | No connection became free within `pool_timeout` | `pool_size: int`, `timeout: float` |
 
 ## Terminology Glossary
 
@@ -880,4 +937,4 @@ RowQueryError
 | **TransactionManager** | A context manager for executing multiple SQL statements atomically. Auto-commits on success, auto-rolls-back on exception. `AsyncTransactionManager` is its async counterpart. |
 | **MigrationManager** | Discovers, tracks, and applies SQL migration files in version order using a `schema_migrations` tracking table. |
 | **Repository** | A DDD-style base class for organizing database access around domain entities. Wraps an Engine and optional mapper. `AsyncRepository` is its async counterpart. |
-| **:name parameter** | The parameter syntax used in SQL queries (e.g., `:id`, `:name`). RowQuery automatically converts this to the format required by each backend. |
+| **:name parameter** | The named parameter syntax used in SQL queries (e.g., `:id`, `:name`). RowQuery automatically converts this to the format required by each backend. Positional `?` placeholders are converted the same way. |

{rowquery-0.1.2 → rowquery-0.2.0}/llms.txt

@@ -13,7 +13,7 @@
 - [Transactions](llms-full.txt#transactions): Sync and async transaction management
 - [Migrations](llms-full.txt#migrations): Schema migration with MigrationManager
 - [Repository Pattern](llms-full.txt#repository-pattern): DDD-style repository base classes
-- [Exception Reference](llms-full.txt#exception-reference): Complete exception hierarchy (18 classes)
+- [Exception Reference](llms-full.txt#exception-reference): Complete exception hierarchy
 - [Terminology Glossary](llms-full.txt#terminology-glossary): Canonical terms used in RowQuery
 
 ## Optional

{rowquery-0.1.2 → rowquery-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rowquery"
-version = "0.1.2"
+version = "0.2.0"
 description = "A SQL-first Python library for querying and mapping data across multiple database backends."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -27,11 +27,11 @@ dependencies = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/maksim-shevtsov/RowQuery"
-Documentation = "https://github.com/maksim-shevtsov/RowQuery#readme"
-Repository = "https://github.com/maksim-shevtsov/RowQuery.git"
-Issues = "https://github.com/maksim-shevtsov/RowQuery/issues"
-Changelog = "https://github.com/maksim-shevtsov/RowQuery/blob/main/CHANGELOG.md"
+Homepage = "https://github.com/MaksimShevtsov/RowQuery"
+Documentation = "https://github.com/MaksimShevtsov/RowQuery#readme"
+Repository = "https://github.com/MaksimShevtsov/RowQuery.git"
+Issues = "https://github.com/MaksimShevtsov/RowQuery/issues"
+Changelog = "https://github.com/MaksimShevtsov/RowQuery/blob/main/CHANGELOG.md"
 
 [project.optional-dependencies]
 postgres = ["psycopg[binary]>=3.1.0"]