# rhosocial-activerecord Documentation

> 🤖 **AI Learning Assistant**: Throughout this documentation, you'll find AI Prompt markers (💡) next to complex concepts. Feel free to ask your AI assistant to explain anything you don't understand.
>
> **Example:** "What is Expression-Dialect separation and why is it important?"
>
> 📖 **For detailed usage:** See [AI-Assisted Development Guide](https://docs.python-activerecord.dev.rho.social/introduction/ai_assistance)

## Table of Contents

1. [**Introduction**](https://docs.python-activerecord.dev.rho.social/introduction/introduction)
   * [**AI-Assisted Development**](https://docs.python-activerecord.dev.rho.social/introduction/ai_assistance): Built-in AI configurations and how to use code agents to accelerate your workflow.
   * [**Glossary**](https://docs.python-activerecord.dev.rho.social/introduction/glossary): Key terms and concepts explained from scratch.
   * [**Coming from Other Frameworks**](https://docs.python-activerecord.dev.rho.social/introduction/coming_from_frameworks): If you know Django, SQLAlchemy, Rails, or others.
   * [**Philosophy**](https://docs.python-activerecord.dev.rho.social/introduction/philosophy): The "Gradual ORM" approach — balancing strict Type Safety (OLTP) with Raw Performance (OLAP).
   * [**Key Features**](https://docs.python-activerecord.dev.rho.social/introduction/key_features):
     * Pydantic V2 Integration
     * Composable Mixins (UUID, Timestamp, Optimistic Locking)
     * [**Sync-Async Parity**](https://docs.python-activerecord.dev.rho.social/introduction/key_features#sync-async-parity): Equivalent functionality across synchronous and asynchronous implementations 💡 *AI Prompt: "Why does this project enforce identical method names for sync and async APIs?"*
     * Zero-IO Testing Strategy
   * [**Technical Decision Guide**](https://docs.python-activerecord.dev.rho.social/introduction/comparison): Which ORM to choose? Scenario-based comparison with SQLAlchemy, Django, SQLModel, and others.
   * [**Competitor Analysis**](https://docs.python-activerecord.dev.rho.social/competitor-analysis/competitor_analysis): In-depth comparison with Django ORM, SQLAlchemy, SQLModel, Peewee, Tortoise ORM, and other mainstream ORMs.
   * [**Architecture**](https://docs.python-activerecord.dev.rho.social/introduction/architecture): Understanding the layered design (Interface -> Active Record -> Dialect -> Expression -> Backend). 💡 *AI Prompt: "Explain the layered architecture and why Expression-Dialect separation matters."*
2. [**Getting Started**](https://docs.python-activerecord.dev.rho.social/getting-started/getting_started)
   * [**Installation**](https://docs.python-activerecord.dev.rho.social/getting-started/installation): Requirements (Python 3.8+, Pydantic V2) and pip installation.
   * [**Configuration**](https://docs.python-activerecord.dev.rho.social/getting-started/configuration): Setting up SQLite and managing shared backend connections.
   * [**Quick Start**](https://docs.python-activerecord.dev.rho.social/getting-started/quick_start): A complete "Hello World" example defining User/Post models and performing CRUD.
   * [**First CRUD App**](https://docs.python-activerecord.dev.rho.social/getting-started/first_crud): Build a complete Todo application from scratch, learning Create, Read, Update, Delete operations step by step.
   * [**Troubleshooting**](https://docs.python-activerecord.dev.rho.social/getting-started/troubleshooting): Running into issues? Common errors and their solutions (No backend configured, FieldProxy missing, PYTHONPATH issues, etc.).
3. [**Modeling Data**](https://docs.python-activerecord.dev.rho.social/modeling-data/modeling)
   * [**Fields & Proxies**](https://docs.python-activerecord.dev.rho.social/modeling-data/fields): Field definition, `FieldProxy`, and mapping legacy columns. 💡 *AI Prompt: "What is FieldProxy and how does it enable type-safe query building?"*
   * [**Mixins**](https://docs.python-activerecord.dev.rho.social/modeling-data/mixins): Reusable logic with built-in (`UUID`, `Timestamp`) and custom Mixins.
   * [**Validation & Hooks**](https://docs.python-activerecord.dev.rho.social/modeling-data/validation): Pydantic validation and lifecycle hooks.
   * [**Custom Types**](https://docs.python-activerecord.dev.rho.social/modeling-data/custom_types): Handling complex data types like JSON and arrays.
   * [**Best Practices**](https://docs.python-activerecord.dev.rho.social/modeling-data/best_practices): Naming conventions, field design, project organization, version control, index optimization.
4. [**Relationships**](https://docs.python-activerecord.dev.rho.social/relationships/relationships)
   * [**Definitions**](https://docs.python-activerecord.dev.rho.social/relationships/definitions): Defining `HasOne`, `BelongsTo`, `HasMany`.
   * [**Many-to-Many**](https://docs.python-activerecord.dev.rho.social/relationships/many_to_many): Implementing complex N:M relations via Through Models.
   * [**Loading Strategies**](https://docs.python-activerecord.dev.rho.social/relationships/loading): Solving N+1 problems with eager loading vs lazy loading.
5. [**Querying Interface**](https://docs.python-activerecord.dev.rho.social/querying-interface/querying)
   * [**ActiveQuery (Model Query)**](https://docs.python-activerecord.dev.rho.social/querying-interface/active_query): Filtering, sorting, joins, aggregation, eager loading.
   * [**CTEQuery (Common Table Expressions)**](https://docs.python-activerecord.dev.rho.social/querying-interface/cte_query): Recursive and analytical queries.
   * [**SetOperationQuery (Set Operations)**](https://docs.python-activerecord.dev.rho.social/querying-interface/set_operation_query): UNION, INTERSECT, EXCEPT.
   * [**Query Cheatsheet**](https://docs.python-activerecord.dev.rho.social/querying-interface/cheatsheet): Quick reference for common query patterns.
   * [**Query Recipes**](https://docs.python-activerecord.dev.rho.social/querying-interface/recipes): Query solutions for common business scenarios.
6. [**Connection Management**](https://docs.python-activerecord.dev.rho.social/connection-management/connection)
   * [**Connection Groups & Manager**](https://docs.python-activerecord.dev.rho.social/connection-management/connection_management): Using `BackendGroup` and `BackendManager` to manage multi-model, multi-database connections.
   * [**Connection Pool**](https://docs.python-activerecord.dev.rho.social/connection-management/connection_pool): Efficient connection management with context-aware access patterns, connection reuse, lifecycle management, and ActiveRecord integration.
7. [**Worker Pool Module**](https://docs.python-activerecord.dev.rho.social/worker-pool-module/worker_pool)
   * [**Worker Pool Guide**](https://docs.python-activerecord.dev.rho.social/worker-pool-module/worker_pool-1): Standalone worker process pool for parallel task execution, with persistent workers, crash recovery, lifecycle hooks, and graceful shutdown.
8. [**Performance**](https://docs.python-activerecord.dev.rho.social/performance/performance)
   * [**Strict vs Raw Modes**](https://docs.python-activerecord.dev.rho.social/performance/modes): When to use `.aggregate()` to bypass Pydantic overhead.
   * [**Concurrency Control**](https://docs.python-activerecord.dev.rho.social/performance/concurrency): Handling race conditions with Optimistic Locking.
   * [**Caching**](https://docs.python-activerecord.dev.rho.social/performance/caching): Understanding internal caching to avoid redundant work.
9. [**Logging**](https://docs.python-activerecord.dev.rho.social/logging/logging)
   * [**Logger Namespace**](https://docs.python-activerecord.dev.rho.social/logging/namespace): Hierarchical logger naming for unified control and fine-grained tuning.
   * [**Data Summarization**](https://docs.python-activerecord.dev.rho.social/logging/data_summarization): Automatic sensitive field masking and long string truncation.
   * [**Per-Logger Configuration**](https://docs.python-activerecord.dev.rho.social/logging/per_logger_config): Setting different summarization modes for different components.
10. [**Events**](https://docs.python-activerecord.dev.rho.social/events/events)
    * [**Lifecycle Events**](https://docs.python-activerecord.dev.rho.social/events/lifecycle): Hooks for Decoupling business logic (before\_save, after\_create, etc.).
11. [**Serialization**](https://docs.python-activerecord.dev.rho.social/serialization/serialization)
    * [**JSON Serialization**](https://docs.python-activerecord.dev.rho.social/serialization/json): Converting models to JSON/Dicts, field filtering.
12. [**Backend System**](https://docs.python-activerecord.dev.rho.social/backend-system/backend)
    * [**Introspection**](https://docs.python-activerecord.dev.rho.social/backend-system/introspection): Querying database structure metadata.
    * [**Query Explain**](https://docs.python-activerecord.dev.rho.social/backend-system/explain): Execute EXPLAIN statements and analyse query plans and index usage.
    * [**Expression System**](https://docs.python-activerecord.dev.rho.social/expression-system/expression): How Python objects are safely transformed into SQL strings. 💡 *AI Prompt: "Explain ToSQLProtocol and how Expression-Dialect separation prevents SQL injection."*
    * [**Custom Backend**](https://docs.python-activerecord.dev.rho.social/backend-system/custom_backend): Implementing a new database driver.
    * [**SQLite Backend**](https://docs.python-activerecord.dev.rho.social/sqlite-backend/sqlite): SQLite-specific features and capabilities.
13. [**Testing**](https://docs.python-activerecord.dev.rho.social/testing/testing)
    * [**Strategies**](https://docs.python-activerecord.dev.rho.social/testing/strategies): Zero-IO Testing vs Integration Testing.
    * [**Dummy Backend**](https://docs.python-activerecord.dev.rho.social/testing/dummy): Using the dummy backend for unit tests.
14. [**Scenarios**](https://docs.python-activerecord.dev.rho.social/scenarios/scenarios)
    * [**FastAPI Integration**](https://docs.python-activerecord.dev.rho.social/scenarios/fastapi): Async support, dependency injection, and Pydantic model reuse.
    * [**GraphQL Integration**](https://docs.python-activerecord.dev.rho.social/scenarios/graphql): Solving N+1 problems with DataLoaders.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.python-activerecord.dev.rho.social/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.