Create Mutations

Relevant source files

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

• src/mutation/entity_create_one_mutation.rs
• src/mutation/entity_create_batch_mutation.rs
• src/mutation/mod.rs
• src/lib.rs
• CHANGELOG.md
• examples/sea-draw/src/schema.rs

Create Mutations in Seaography provide a mechanism to insert new records into a database through a GraphQL API. This system automatically bridges SeaORM entities and async-graphql dynamic schemas, allowing for both single-record insertions and bulk batch operations. The framework handles the conversion of GraphQL input objects into SeaORM ActiveModels, executes the database insertion, and returns the newly created entities.

The system is designed to be highly extensible through the use of Lifecycle Hooks and guards, which allow developers to implement authorization, validation, and custom logic during the creation process. Sources: src/lib.rs, src/mutation/mod.rs

Architecture and Components

The creation system is built around two primary builders that generate the necessary GraphQL fields for a given SeaORM entity.

EntityCreateOneMutationBuilder

This builder is responsible for creating a mutation that accepts data for a single entity and returns the created model. It identifies the target entity, parses the input data, applies security guards, and performs the insertion. Sources: src/mutation/entity_create_one_mutation.rs:34-36

EntityCreateBatchMutationBuilder

This builder handles bulk insertions. It accepts an array of entity data objects and executes the insertions within a database transaction. If any insertion fails or is blocked by a guard, the entire transaction is rolled back. Sources: src/mutation/entity_create_batch_mutation.rs:34-36, src/mutation/entity_create_batch_mutation.rs:77-124

Data Flow for Creation

The following diagram illustrates the flow of data from a GraphQL request through the Seaography mutation layer to the database.

The flow ensures that security checks are performed at both the entity and field levels before any database interaction occurs. Sources: src/mutation/entity_create_one_mutation.rs:64-106, src/mutation/entity_create_batch_mutation.rs:65-115

Implementation Details

ActiveModel Preparation

The prepare_active_model function is a critical internal utility used by both "Create One" and "Create Batch" mutations. It maps GraphQL input fields to SeaORM columns, specifically skipping auto-increment primary keys to allow the database to handle ID generation. Sources: src/mutation/entity_create_one_mutation.rs:118-151

pub fn prepare_active_model<T, A>(
    entity_input_builder: &EntityInputBuilder,
    entity_object_builder: &EntityObjectBuilder,
    input_object: &ObjectAccessor<'_>,
) -> async_graphql::Result<A>
where
    T: EntityTrait,
    <T as EntityTrait>::Model: IntoActiveModel<A>,
    A: ActiveModelTrait<Entity = T> + sea_orm::ActiveModelBehavior + Send,
{
    let mut data = entity_input_builder.parse_object::<T>(input_object)?;
    let mut active_model = A::default();

    for column in T::Column::iter() {
        let auto_increment = match <T::PrimaryKey as PrimaryKeyToColumn>::from_column(column) {
            Some(_) => T::PrimaryKey::auto_increment(),
            None => false,
        };

        if auto_increment { continue; }

        if let Some(value) = data.remove(&entity_object_builder.column_name::<T>(&column)) {
            active_model.try_set(column, value)?;
        }
    }
    Ok(active_model)
}

Sources: src/mutation/entity_create_one_mutation.rs:118-151

Configuration Options

The behavior of create mutations can be customized through configuration structures within the BuilderContext.

Option	Type	Default (PascalCase)	Description
mutation_suffix	String	"CreateOne" / "CreateBatch"	Suffix appended to the entity name for the mutation field.
data_field	String	"data"	The name of the argument containing the input data.

Note: If the field-snake-case feature is enabled, defaults change to _create_one and _create_batch. Sources: src/mutation/entity_create_one_mutation.rs:15-32, src/mutation/entity_create_batch_mutation.rs:15-32

Lifecycle Hooks and Guards

Seaography provides a robust hook system to intercept the creation process. This is managed via the LifecycleHooksInterface.

1. Entity Guard: Checked at the start of the mutation. Can block the entire operation based on the OperationType::Create.
2. Field Guard: Checked for every field present in the input data. Allows for fine-grained access control (e.g., preventing certain users from setting specific columns).
3. Before ActiveModel Save: Triggered after the ActiveModel is prepared but before it is sent to the database. This allows for manual modification of the model or final validation.
4. Entity Watch: Triggered after a successful insertion, useful for triggering side effects like cache invalidation or notifications.

Sources: CHANGELOG.md:46-77, src/mutation/entity_create_one_mutation.rs:65-106, examples/sea-draw/src/schema.rs:125-144

Sequence of Hooks in Batch Creation

The batch mutation uses a transaction to ensure atomicity when processing multiple inputs.

Summary

Create Mutations in Seaography automate the boilerplate of database insertions by dynamically mapping SeaORM entities to GraphQL. By supporting both single and batch operations with integrated transaction management and a comprehensive lifecycle hook system, it provides a secure and flexible foundation for building data-driven APIs. Sources: src/lib.rs, CHANGELOG.md