DOCSEARCHbyAlgolia
Submit Docs

FastCRUD

repository·main·Indexed 23 days ago

https://github.com/benavlabs/fastcrud

A Python package for FastAPI that provides asynchronous CRUD operations and automatic endpoint generation using SQLAlchemy 2.0 and Pydantic V2. It features the crud_router for rapid endpoint creation, advanced filtering with suffix operators, batch updates and deletes, and complex joined queries including one-to-one, one-to-many, and many-to-many relationships.

Tokens
37.8K
Snippets
101
Records
148
Agent score
82%

What's inside fastcrud

  1. Overview of Automatic CRUD Endpoints

    main

    FastCRUD automatically generates several standard RESTful endpoints for your FastAPI application. The available endpoints and their behaviors are:

    Create

    • Endpoint: /{model}
    • Method: POST
    • Request Body: JSON based on create_schema.
    • Response: Returns the created item data if select_schema is provided; otherwise returns null.

    Read

    • Endpoint: /{model}/{id}
    • Method: GET
    • Description: Retrieves a single item by its ID.

    Read Multiple

    • Endpoint: /{model}
    • Method: GET
    • Description: Retrieves multiple items with support for pagination and sorting.
    • Query Parameters:
      • offset (optional): Starting point for fetching.
      • limit (optional): Maximum items to return.
      • page (optional): Page number (starts at 1).
      • itemsPerPage (optional): Number of items per page.
      • sort (optional): Sort fields. Format: field1,-field2 (prefix - for descending).

    Update

    • Endpoint: /{model}/{id}
    • Method: PATCH
    • Request Body: JSON based on update_schema.
    • Note: Returns 404 if the item is not found.

    Delete

    • Endpoint: /{model}/{id}
    • Method: DELETE
    • Description: Performs a soft delete if configured.

    DB Delete (Hard Delete)

    • Endpoint: /{model}/db_delete/{id}
    • Method: DELETE
    • Requirement: Requires a delete_schema to be provided.
    • Description: Permanently removes the item from the database.

  2. Advanced Usage Overview

    main

    The advanced features of FastCRUD allow for complex query construction, bulk data handling, and sophisticated endpoint management. Key capabilities include:

    • Advanced Filtering: Using comparison operators, pattern matching, and logical operations (OR/NOT).
    • Bulk Operations: Performing mass updates, deletes, and inserts for large datasets.
    • Soft Delete: Implementing custom columns for soft deletes and configuring queries to exclude deleted records.
    • Advanced Endpoint Management: Using EndpointCreator and crud_router for custom routes and selective method exposure.
    • Complex Joins: Utilizing get_joined and get_multi_joined for multi-model and self-joins.
    • Query Construction: Using method chaining with .select() for dynamic filters and sorting.
    • Response Customization: Configuring the multi_response_key to change the key used for list responses.

    Prerequisites: To use these features effectively, a solid understanding of FastAPI, SQLAlchemy, and Pydantic is highly recommended.

  3. Core components of FastCRUD

    main

    FastCRUD's API is built around several key components designed to automate CRUD operations and FastAPI integration:

    • FastCRUD Class: The central class for performing Create, Read, Update, and Delete operations on database models.
    • EndpointCreator Class: A utility used to create and register CRUD endpoints directly into a FastAPI application.
    • crud_router Function: A high-level function that generates and configures a FastAPI router pre-populated with standard CRUD endpoints for a specific model.
    • paginated Module: Provides utilities for offset-based pagination.

    Note on Pagination: As of version 0.18.0, pagination utilities have been moved to the core module. While fastcrud.paginated is deprecated, it is still available for backward compatibility.

  4. Overview of FastCRUD Agent Skill capabilities

    main

    The FastCRUD Library Skill provides AI agents with deep context regarding the library's API and best practices. The skill is structured using progressive disclosure, meaning the agent only loads full reference details when needed.

    Key areas covered by the skill include:

    • Canonical Setup: The minimal pattern for models, schemas, and crud_router.
    • Method Selection: Guidance on choosing between get, get_joined, and get_multi_joined to avoid N+1 problems.
    • N+1 Prevention: Using include_relationships=True, JoinConfig, and nested_limit.
    • Pagination Safety: Understanding the limit=None footgun and the three-tier pagination default.
    • Limitations: When to avoid FastCRUD (e.g., aggregate roll-ups, CTEs, GROUP BY, or bulk writes).
    • Return Semantics: Understanding that create() returns None by default and how to use return_as_model=True with schema_to_select.
    • Filter Syntax: Using __op suffixes, joined filters with ., and Depends(...) filters.
    • Advanced Topics: Soft delete behavior, joined-table inheritance, and SQLModel polymorphism caveats.

  5. Use pure functions for data transformation in Core Logic

    main

    The Core Logic Layer (Level 2) uses pure functions in core/data/transforms.py to reshape data. These functions take input (like flat join results) and produce output (like nested objects) without side effects, making them easy to test and stable.

    def handle_one_to_many(data: List[Dict], nested_key: str) -> List[Dict]:
    """Transform flat join results into nested structures.""
    # Pure function - same input always produces same output
    pass

  6. Evaluate if FastCRUD is right for your project

    main

    FastCRUD is best suited for projects requiring standard CRUD operations with automatic filtering, pagination, and OpenAPI documentation. It uses a Django-style filtering syntax (e.g., __gt, __in, __between) which differs from raw SQLAlchemy.

    Project Fit Summary

    Project TypeFastCRUD FitWhy
    Modular monolithsExcellentConsistent patterns across modules, shared infrastructure
    Admin dashboardsExcellentStandard CRUD with filtering, minimal custom logic
    REST APIsVery goodConsistent endpoints, pagination, OpenAPI docs
    MicroservicesVery goodEach service has focused CRUD operations
    Analytics platformsMixedGood for user/config management, poor for reporting queries
    Workflow enginesPoorState transitions, complex business rules
    High-frequency tradingPoorHand-optimized queries, microsecond performance

    When to use selectively or avoid

    • Analytics Applications: Use FastCRUD for user/config management, but use custom SQL for complex aggregations.
    • Performance-Critical Systems: Use FastCRUD for admin interfaces, but use hand-optimized queries for core logic.
    • Domain-Driven Design: Use FastCRUD for simple entities, but use custom code for complex aggregates.

  7. How dependency-based filtering works

    main

    When a callable is provided in FilterConfig, FastCRUD performs the following steps at runtime for each request:

    1. Uses FastAPI's Depends mechanism to inject the dependency into the endpoint.
    2. Executes the dependency function to resolve the actual filter value.
    3. Applies the resolved value as a filter to the database query.

    This allows the filter value to be dynamically determined by the request context (e.g., the current user's session or token).

  8. Get nested relationship data with nest_joins

    main

    To receive a hierarchical response structure where related data is nested within the parent object (rather than flattened), set nest_joins=True. This is required when fetching one-to-many relationships.

    user = await user_crud.get_joined(
    db=db,
    auto_detect_relationships=True,
    nest_joins=True,
    id=1,
)
# Response structure:
# {
#     "id": 1,
#     "name": "Alice",
#     "tier": {
#         "id": 1,
#         "name": "Premium"
#     },
#     "department": {
#         "id": 5,
#         "name": "Engineering"
#     }
# }

  9. Perform OR operations across multiple fields

    main

    To implement search functionality across different fields (e.g., searching for a keyword in both name and email), use the special _or parameter. This parameter accepts a dictionary of filter expressions.

    # Find users with name containing 'john' OR email containing 'john'
results = await crud.get_multi(
    db,
    _or={
        "name__ilike": "%john%",
        "email__ilike": "%john%"
    }
)

  10. Use EndpointCreator to register CRUD endpoints in FastAPI

    main
    The EndpointCreator class is used to automate the creation and registration of standard CRUD (Create, Read, Update, Delete) endpoints within a FastAPI router. It abstracts the boilerplate required to map database operations to HTTP methods, allowing you to quickly expose your models via an API.

  11. How the Orchestration Layer builds SQLAlchemy queries

    main

    The Orchestration Layer (Level 3) converts high-level filter configurations into actual SQLAlchemy queries. It takes the pure logic defined in the Core Logic layer (like filter parsing) and uses it to compose select statements.

    # Takes filter config from core logic
filters = {"name__icontains": "admin", "status": "active"}

# Builds actual SQLAlchemy query
query = select(User).where(
    User.name.ilike("%admin%"),
    User.status == "active"
)

  12. Understand the FastCRUD Six-Layer Architecture

    main

    FastCRUD is organized into a strict six-layer dependency hierarchy to ensure maintainability and scalability. Dependencies flow in one direction: Framework → CRUD → Integration → Orchestration → Core → Foundation. This separation allows you to isolate issues: if joins fail, look at the Integration layer; if filter parsing is incorrect, check Orchestration; if data transformation fails, check Core Logic.

    Layer Summary

    1. Foundation (Level 1): Building blocks like database introspection, type definitions, and Protocols to prevent circular dependencies.
    2. Core Logic (Level 2): Pure business logic (filtering rules, pagination math, data transformations) with no database or framework dependencies.
    3. Orchestration (Level 3): Coordinates core logic to build SQLAlchemy queries and manage field selection.
    4. Integration (Level 4): Bridges database results and API responses, handling complex join processing and response formatting.
    5. CRUD (Level 5): The main public interface (e.g., FastCRUD class) providing methods for Create, Read, Update, and Delete operations.
    6. Framework (Level 6): FastAPI-specific implementations like dependency injection and automatic endpoint generation.