rowquery 0.1.0__tar.gz → 0.2.0__tar.gz

{rowquery-0.1.0 → 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.0 → 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
@@ -66,3 +72,8 @@ uv run mypy row_query/     # Type check (strict mode)
 ## Active Technologies
 - Python >=3.10 + pydantic >=2.0.0 (core); psycopg >=3.1.0, aiosqlite, aiomysql, oracledb (optional per-backend)
 - SQLite, PostgreSQL, MySQL, Oracle via adapter pattern
+- Python >=3.10 (documented library) + N/A (documentation-only feature; no new code dependencies) (001-llm-docs)
+- N/A (static markdown/text files in repository) (001-llm-docs)
+
+## Recent Changes
+- 001-llm-docs: Added Python >=3.10 (documented library) + N/A (documentation-only feature; no new code dependencies)

{rowquery-0.1.0 → 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.0 → rowquery-0.2.0}/PKG-INFO

@@ -1,12 +1,12 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: rowquery
-Version: 0.1.0
+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.0 → 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