Delete Mutations

Relevant source files

The following files were used as context for generating this wiki page:

• src/mutation/entity_delete_mutation.rs
• src/mutation/entity_update_mutation.rs
• examples/postgres/tests/mutation_tests.rs
• CHANGELOG.md
• examples/sqlite/tests/hook_guard_tests.rs
• examples/sea-draw/src/schema.rs
• src/lib.rs

Introduction

Delete Mutations in Seaography provide a standardized mechanism for removing entities from a database via GraphQL. This module enables the dynamic generation of mutation fields that take an entity condition filter object as input, perform the deletion using SeaORM's delete_many functionality, and return the number of affected rows to the client.

The system is designed to be extensible, allowing for the integration of lifecycle hooks and guards. These hooks can restrict deletion access at the entity level or inject additional filters to ensure users only delete data they are authorized to access.
Sources: CHANGELOG.md:214-216, src/mutation/entity_delete_mutation.rs:1-10

Architecture and Components

EntityDeleteMutationBuilder

The EntityDeleteMutationBuilder is the core component responsible for generating GraphQL fields for deletion operations. It utilizes the BuilderContext to align with project-wide naming conventions and configuration settings.

The builder performs several key steps:

1. Naming: It generates a unique mutation name (e.g., actorDelete or actor_delete) based on the entity type and configured suffix.
2. Argument Construction: It adds a filter argument using the FilterInputBuilder to allow complex conditional deletions.
3. Execution Logic: It defines the resolver that handles database interaction, including hook verification and SeaORM execution.
   Sources: src/mutation/entity_delete_mutation.rs:36-103

Configuration

The EntityDeleteMutationConfig structure allows developers to customize the appearance of delete mutations in the GraphQL schema.

Option	Type	Default Value	Description
mutation_suffix	String	"Delete" or "_delete"	Appended to the entity name to form the mutation field name.
filter_field	String	"filter"	The name of the argument used for filtering entities to be deleted.

Sources: src/mutation/entity_delete_mutation.rs:13-33

Execution Flow

The following sequence diagram illustrates the lifecycle of a delete mutation request, from the GraphQL query to the database execution and hook calls.

Security and Guards

Lifecycle Hooks

Seaography utilizes a LifecycleHooksInterface to provide fine-grained control over deletion operations.

• Entity Guard: Checked before any database logic begins. If the guard returns GuardAction::Block, the mutation fails immediately.
• Entity Filter: Allows the system to automatically append mandatory conditions (e.g., tenant_id = X) to the delete statement, preventing unauthorized data access even if the client's filter is broad.
• Entity Watch: Triggered after a successful deletion, useful for logging, cache invalidation, or side effects.

Guard Implementation Example

In hook_guard_tests.rs, the entity_guard is used to block deletions for specific entities like FilmCategory.

fn entity_guard(&self, ctx: &ResolverContext, entity: &str, action: OperationType) -> GuardAction {
    match entity {
        "FilmCategory" => GuardAction::Block(None),
        _ => GuardAction::Allow,
    }
}

Sources: examples/sqlite/tests/hook_guard_tests.rs:125-140, src/mutation/entity_delete_mutation.rs:74-78

Usage in Testing

The functionality is verified through integration tests that ensure deletions correctly update the database state and return the expected row counts.

#[tokio::test]
async fn test_delete_mutation() {
    let schema = schema().await;
    // ... setup code ...
    assert_eq(
        schema.execute(r#"
            mutation {
                languageDelete(filter: { languageId: { gt: 6 } })
            }
        "#).await,
        r#" { "languageDelete": 3 } "#
    );
}

Sources: examples/postgres/tests/mutation_tests.rs:564-644, examples/mysql/tests/mutation_tests.rs:420-496

Summary

Delete Mutations serve as a robust interface for data removal in Seaography. By integrating closely with SeaORM's query filtering and providing a comprehensive hook system, the module ensures that deletions are both powerful for developers and secure against unauthorized use. The return of rows_affected provides immediate feedback on the impact of the operation.
Sources: src/mutation/entity_delete_mutation.rs:98, CHANGELOG.md:214-216