# 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.
   * [**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.